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PREFACE 



About This Book 



This book. Inside Macintosh: Files, describes the parts of the Macintosh 
Operating System that allow you to manage files. It shows in detail how your 
application can handle the commands typically found in a File menu. It also 
provides a complete technical reference to the File Manager, the Standard File 
Package, the Alias Manager, and other fde-related services provided by the 
system software. 

If you are new to the Macintosh Operating System, you should begin with the 
chapter "Introduction to File Management." This chapter describes the basic 
structure of Macintosh files and the hierarchical file system (HFS) used with 
Macintosh computers, and it shows how you can use the services provided by 
the Standard File Package, the File Manager, the Finder, and other system 
software components to create, open, update, and close files. Because this 
chapter is designed to be largely self-contained, the reference and summary 
sections in this chapter are subsets of the corresponding sections from the 
other chapters in this book. 

Once you are familiar with basic file management on Macintosh computers, 
you might want to read other chapters in this book. The chapter "File 
Manager" describes how your application can manage shared files; search 
for specific files in a volume; obtain information about files, directories, and 
volumes; and perform other advanced operations. This chapter also describes 
how the File Manager organizes file and directory data on disk and in 
memory. Much of this information is of interest only to designers of very 
specialized applications or file-system utility programs. 
If you want to customize the user interface for naming and identifying files, 
you need to read the chapter "Standard File Package." It provides complete 
information on how to customize and display the dialog boxes that let the 
user specify the names and locations of files to be saved or opened. 
If your application needs to keep track of particular files, directories, or 
voluihes, you rrught want to use Oie Alias Manager. It helps you fiiid objects 
in the file system, even if those objects have been moved or renamed. See the 
chapter "Alias Manager" for complete details. 

The chapter "Disk Initialization Manager" shows how you can initialize disks 
and erase the contents of previously initialized disks. The Disk Initialization 
Manager provides a routine that allows you to present the standard user 
interface for initializing and naming disks. Most applications should call that 
routine whenever they receive ^ disk-ii\serted event and the inserted disk 
is invalid. 



XV 



TIVO-408378 



PREFACE 



Format of a Typical Chapter 



Almost all chapters in this book follow a standard structure. For example, the 
Chapter "Standard File Package" contains these sections: 

■ "About the Standard File Package." This section provides an overview of the 
features provided by the Standard File F'ackage. 

m "Using the Standard File Package." This section describes the tasks you can 
accomplish using the Standard FUe Package. It describes how to use the 
niost commoti routines, gives related user interface information, provides 
code samples, and supplies additional information. 

■ "Standard File Package Reference." This section provides a complete 
reference to the Standard File Package by describing the data structures and 
routines that it uses. Each routine description also follows a standard format, 
which gives the routine declaration and a description of every parameter of 
the routine. Some routine descriptions also give additional descriptive 
information, such as assembly-lang;uage information or result codes. 

■ "Summary of the Standard Hie Package." This section provides the 
Standard File Package's Pascal interface, as well as the C interface, for the 
constants, data structures, routines, and result codes associated with the 
Standard File Package. It also includes irelevant assembly-language 
interface information. 

Some chapters contain additional main sections that provide more detailed 
discussions of certain topics. For example, the chapter "File Manager" 
contains the section "Identifying Files, Directories, and Volumes," which 
describes the many ways to identify objects in the file system. That chapter 
also contains the two advanced sections 'T)ata Organization on Volumes" 
and "Data Organization in Memory." 

Conventions Used in This Book 



inside Macintosh uses various conventions to present information. Words that 
irequire special treatment appear in specific fonts or font styles. Certain 
information, such as parameter blocks, use special formats so that you can 
scan them quickly. 

Special Fonts 

All code listings, reserved words, and the names of actual data structures, 
constants, fields, parameters, and routines are shown in Courier (this 
is Courier).' 

Words that appear in boldface are key terms or concepts and are defined in 
the Glossary 
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PREFACE 



Types of Notes 

There are several types of notes used in this book. 
Note 

A note like this contains information that is interesting but possibly not 
essential to an understanding of the main text. (An example appears on 
page 1-6.) ♦ 

IMPORTANT 

A note like this contains information that is essential for an 
understanding of the main text. (An example appears on page 1-6.) A 

A WARNING 

Warnings like this indicate j5otential problems that you should be aware 
of as you design your application. Failure to heed these warnings could 
result in system crashes or loss oiF data. (An example appears on 
page 1-46.) A 

Asse mbly-Language Information 

Inside Macintosh provides information about the registers for specific routines 
like this: 

Registers on entry 

AO Contents of register AO on entry 

Registers on exit 

DO Contents of register DO on exit 

In addition. Inside Macintosh presents information about the fields of a 
parameter block in this format: 

Parameter block 

^ inAndOut Integer Input/output parameter. 

<r- output 1 Ptt Output parameter. 

^ input 1 Ptr Input paranieter. 

The drtow in the far left column indicates whether the AeiA is an input 
parameter, output parameter, or both. You must supply values for all input 
parameters and input/ output parameters. The routine returns values iii 
output parameters and input/ output parameters. 

The second column shows the field name as defined in the MPW Pascal 
interface files; the third column indicates the Pascal data type of that field. 
The fourth column provides a brief description of the use of the field. For a 
complete description of each field, see the discussion that follows the 
parameter block or the description of the parameter block in the reference 
section of the chapter. 

xvii 



TIVO-408380 



PREFACE 



Development Environment 



The system software routines described in this book are available using 
Pascal, C, or assembly-language interfaces. How you access these routines 
depends on the development environment you are using. This book shows 
system software routines in their Pascal interface using the Macintosh 
Programmer's Workshop (MPW). 

All code listings in this book are shovm in Pascal. They show methods of 
using various routines and illustrate techniques for accomplishing particular 
tasks. All code listings have been compiled and, in most cases, tested. 
However, Apple Computer does not intend that you use these code samples 
in your application. 

This book occasionally uses SurfDraw as the name of a sample application for 
illustrative purposes; this is not an actual product of Apple Computer, Inc. 

APDA, Apple's source for developer tools, offers worldwide access to a broad 
range of programming products, resources, and information for anyone 
developing on Apple platforms. You'll find the most current versions of 
Apple and third-party development tools, debuggers, compilers, languages, 
and technical references for all Apple platforms. To establish an APDA 
account, obtain additional ordering information, or find out about site 
licensing and developer training programs, contact 

APDA 

Apple Computer, Inc. 

20525 Mariani Avenue, M/S 33-G 

Cupertino, CA 95014-6299 

Telephone: 800-282-2732 (United States) 
800-637-0029 (Canada) 
800-562-3910 (elsewhere in the world) 

Fax: 408-562-3971 

Telex: 171-576 

If you provide commercial products and services, call 408-974-4897 for 
information on the developer support programs available from Apple. 

For information on registering signatures, file types, Apple events, and other 
technical information, contact 

Macintosh Developer Technical Support 
Apple Computer, Inc. 
20525 Mariani Avenue, M/S 75-3T 
Cupertino, CA 95014-6299 
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Introduction to File Management 

This chapter is a general introduction to file managen\ent on Macintosh computers. It 
explains the basic structure of Macintosh files and the hierarcHcal file system (HFS) used 
with Macintosh computers, and it shows how you can use the services provided by the 
Standard File Package, the File Manager, the Finder, and other system software 
components to create, open, update, and close files. 

You should read this chapter if your application implements the conunands typically 
found in an application's File menu— except for printing conunands and the Quit 
command, which are described elsewhere. This chapter describes how to 

■ create a new fOe 

■ open an existing file 

■ close a file 

■ save a document's data in a file 

■ save a dociunent's data in a file under a new name 

■ revert to the last saved version of a file 

■ create and read a preferences file 

Depending on the requirements of your application, you may be able to accomplish all 
your file-related operations by following the instructions given in this chapter. If your, 
application has more specialized file management needs, you'U need to read some or all 
of the remaining chapters in this book- 

This chapter assumes that your application is running in an environment in which the 
routines that accept file system specification records (defined by the FSSpec data type) 
are available. File system specification records, introduced in system software version 7.0, 
simplify the identification of objects in the file system. Your development environment 
may provide "glue" that allows you to call those routines in earlier system software 
versions. If such glue is not available and you want your application to run in system 
software versions earlier than version 7.0, you need to read the discussion of HFS 
file-manipulation routines in the chapter ''File Manager" in this book. 
This chapter begins with a description of files and their organization into directories and 
volumes. Then it describes how to test for the presence of the routines that accept FSSpee 
records and how to use those routines to perform the file management tasks listed above. 
The d\apter ends with descriptions of the data structures and routines used to perforai 
these tasks. The "File Management Reference" and "Summary of File Management'^ 
sections in this chapter are subsets of the corresponding sections of the remaining 
chapters in this book. 
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About Files 



To the user, a file is simply some data stored on a disk. To your application, a file is a 
named, ordered sequence of bytes stored on a Macintosh volume, divided into two forks 
(as described in the following section> "File Forks"). The information in a file can be used 
for any of a variety of purposes. For example, a file might contain the text of a letter or 
the numerical data in a spreadsheet; these types of files are usually known as documents. 
Typically a document is a file that a user can create and edit. A document is usually 
associated with a single application, which the user expects to be able to open by 
double-clicking the document's icon in the Finder. 

A file might also contain an application. In that case, the information in the file consists 
of the executable code of the application itself and any application-specific resources and 
data. Applications typically allow the user to create and manipulate documents. Some 
applications also create special files in which they store user-specific settings; such files 
are known as preferences files. 

The Macintosh Operating System also uses files for other purposes. For example, the File 
Manager uses a special file located in a volume to maintain the hierarchical organization 
of files and folders in that voliune. This special file is called the volume's catalog file. 
Similarly, if virtual memory is in operation, the Operating System stores unused pages of 
memory in a disk file called the backing-store file. 

No matter what its function, each file shares certain characteristics with every other file. 
This section describes these general characteristics of Macintosh files, including 

■ £Qe forks 



file size and access characteristics 

file system organization 

file naming and identification 



File Forks 

Many operating systems treat a file simply as a named, ordered sequence of bytes 
(possibly terminated by a byte having a special value that indicates the end-of-file). As 
illustrated in Figure 1-1, however, each Macintosh file has two forks, known as the data 
fork and the resource fork. 

A file's resource fork contains that file's resources. If the file is an application, the 
resource fork t3^ically contains resources that describe the application's menus, dialog 
boxes, icons, and even the executable code of the application itself. A particularly 
important resource is the application's 'SIZE * resource, which contains information 
about the capabilities of the application and its run-time memory requirements. If the file 
is a document, its resource fork typically contains preference settings, window locations, 
and document-specific fonts, icons, and so forth. 
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Figure 1-1 



The two forks of a Macintosh file 
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A file's data fork contains the file's data. It is simply a series of consecutive bytes of data. 
In a sense, the data fork of a Macintosh file corresponds to an entire file in operating 
systems that treat a file simply as a sequence of bytes. The bytes stored in a file's data 
fork do not have to exhibit any internal struchire, unlike the bytes stored in the resource 
fork (which consists of a resource map followed by resources). Rather, your application 
is responsible for interpreting the bytes in the data fork in whatever manner is appropri- 
ate. The data fork of a document file might, for example, contain the text of a letter. 
Even though a Macintosh file always contains both a resource fork and a data fork, one 
or both of those forks can be empty. Dociunent files sometimes contain orUy data (in 
which case the resource fork is empty). More often, document files contain both 
resources and data. Application files generally contain resources only (in which case, the 
data fork is empty). Application files can, however, contain data as well. 
Whether you store specific data in the data fork or in the resource fork of a file depends 
largely on whether that data can usehiUy be structured as a resource. For example, if you 
want to store a small number of names and telephone niuribers, you can easily define a 
resource type that pairs eadi name with its tdiephone number. Hien you can read names 
and corresponding numbers from the riesource file by using Resource Manager routines. 
To retrieve the data stored ir\ a resource, you simply specify the resource type and ID; 
you don't need to know, for instance, how many bytes of data are stored in that resource. 

In some cases, however, it is not possible or advisable to store your data in resources. 
The data might be too difficult to put into the structure required by the Resource 
Manager. For example, it is easiest to store a document's text, which is usually of 
variable length, in a file's data fork. Then you can use File Manager routines to access 
any by te or group of bytes individually. 
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Even when it is easy to define a resource type for your data, limitations on the Resource 
Manager might compel you to store your data in the data fork instead. A resource fork 
can contain at most about 2700 resources. More importantly, the Resource Manager 
searches linearly through a file's resource types and resource IE>s. If the number of types 
or IDs to be searched is large, accessing the resource data can become slow. As a rule of 
thumb, if you need to manage data that would occupy more than about 500 resoturces 
total, you should use the data fork instead. 

IMPORTANT 

In general, you Shovdd store data created by the user tn a file's data fork, 
unless the data is guaranteed to occupy a small number of resoturces. 
The Resoiurce Manager was not designed to be a general-ptupose data 
storage and retrieval systeih. Also, the Resource Manager does not 
support multiple access to a file's resource fork. If you want to store data 
tha t can be accessed by multiple users of a shared volume, use the 
data fork, a 

Because the Resource "Manager is of limited use in storing large amounts of 
user-generated data, most of the techniques in "Using Files" (beginning on page 1-12) 
illustrate the use of File Manager routines to manage information stored in a file's data 
fork. See the section "Using a Preferences File" on page 1-36 for an example of the use of. 
the Resource Manager to access data stored in a file's resource fork. 

File Size 

The size of a file is usually limited only by the size of its volume. A volume is a portion 
of a storage device that is formatted to contain files. A volume can be an entire disk or 
only a part of a disk. A 3.5-inch floppy disk, for instance, is always formatted as one 
volume. Other memory devices, such as hard disks and file servers, can contain multiple 
volumes. 

Note 

Actually, a file on an HFS volume can be as large as 2 GB ($7FFFFFFF 
bytes). Most volumes are not large enough to hold a file of that size. An 
HPS volume currently can be as large as 2 GB. ♦ 

The size of a volume varies froini oi\e type of device to another. Voliiines are formatted 
into chtmks known as logical blocks, each of which can contain tip to 512 bytes. A 
double-sided 3.5-inch floppy disk, for instance, usually has 1600 logical blocks, or 800 KB. 

Generally, however, the size of a logical block on a volume is of interest only to the disk 
device driver. This is because the File Manager ajways allocates space to a file in units 
called allocation blocks. An allocation block is a group of cor\secutive logical blocks. The 
File Manager can. access a maximum of 65,535 allocation blocks on any volume. For 
small volumes, such as volumes on floppy disks, the File Manager uses an allocation 
block size of one logical block. To support volumes larger than about 32 MB, the File 
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Manager needs to use an allocation block size that is at least two logical blocks. To 
support volumes larger than about 64 MB, the File Manager needs to use an allocation 
block that is at least three allocation blocks. In this way, by progressively increasing 
the number of logical blocks in an allocation block, the File Manager can handle 
larger and larger volumes. Figure 1-2 illustrates how logical blocks are grouped into 
allocation blocks. 



Figure 1-2 Logical blocks and allocation blocks 
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The size of the allocation blocks on a volume is determined when the volume is 
initialized and depends on the number of logical blocks it contains. In general, the 
Disk Initialization Manager uses the smallest allocation block size that will allow the 
File Manager to address the entire volume. A nonempty file fork always occupies at least 
one allocation block, no matter how many bytes of data that file for^ contains. On a 
40 MB volume, for example, a file's data fork occupies at least 1024 bytes (that is, two 
logical blocks), even if it contains only 11 bytes of actual data. 

To distinguish between the amotmt of space allocated tb a file and the riumber of bytes of 
actualfiata in the file, two ntunbers are used to describe tiie size of a file. The physical 
etid-of-file is the nxmiber of bytes currently allocated to the file; it's 1 greater than the 
number of the last byte in its last allocation block (since the first byte is byte number 0). 
As a result, the physical end-of-file is always an exact multiple of the allocation block 
size. The logical end-of-file is the nimiber of those allocated bytes that currently contain 
data; it's 1 greater than the nimiber of the last byte in the file that contains data. For 
example, on a volume having an allocation block size of two logical blocks (that is, 
1024 bytes), a file with 509 bytes of data h^s a logical end-of-file of 509 and a physical 
end-of-file of 1024 (see Figure 1-3). 
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Figure 1-3 Logical end-of~file and physical end-of-file 
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You can move the logical ei\d-of-file to adjust the size of the file. When you move the 
logical end-of-file to a position more than one allocation block short of the current 
physical end-of-file, the File Manager automatically deletes the unneeded allocation 
block from the file. Similarly, you can increase the size of a file by moving the logical 
end-of-file past the physical end-of-file. When you move the logical end-of-file past the 
physical end-of-file, the File Manager automatically adds one or more allocation blocks 
to the file. The number of allocation blocks added to the file is determined by the 
volume's clump size. A clump is a group of contiguous aDocation blocks. The purpose of 
enlarging files always by adding clvunps is to reduce file fragmentation on a volume, 
thus improving the efficiency of read and write operations. 

If you plan to keep extending a file with multiple write operations and you know in 
advance approximately how large the file is likely to become, you should first call the 
SetEOF function to set the file to that size (instead of having the File Manager adjust 
the size each time you write past the end-of-file). Doing this reduces file fragmentation 
and improves I/O performance. 



File Access Characteristics 

A file can be opei\ or dosed. Your application can perform certain operations, such as 
reading and writing data, only on open files. It can perform other operations, such as 
deleting, only on closed files. 

When you open a file, the File Manager reads information about the file from its volume 
and stores that information in a file control block (FCB). The File Manager also creates 
an access path to the file, a desoriptiori of the route to be followed when accessing the 
file. The access path specifies the volvune on which the file is located and the location of 
the file on the volimie. Each access path is assigned a unique file reference number 
(some number greater than 0) by which yoiu" application refers to the path. Multiple 
access paths can be opened to the same file. 
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For each open access path to a file, the FUe Manager maintains a current position marker, 
called the file mark, to keep track of where it is in the file during a read or write 
operation. The mark is the number of the next byte that will be read or written; each time 
a byte is read or written, the mark is moved. When, during a write operation, the mark 
reaches the number of the last byte currently allocated to the file, the File Manager adds 
another clump to the file. 

You can read bytes from and write bytes to a file either singly or in sequences of virtually 
unlimited length. You can specify where each read or write operation should begin by 
setting the mark or specifying an offset; if you don't, the operation begins at the current 
file mark. 

Each time you want to read or write a file's data, you need to pass the address of a data 
buffer, a part of RAM (usually in your application's heap). The File Manager uses the 
buffer when it transfers data to or from your application. You can use a single buffer for 
each read or write operation, or change the address and size of the buffer as necessary. 

When your application writes data to a file, the File Manager transfers the data from 
your application's data buffer and writes it to the disk cache, a part of RAM (usually in 
the System heap). The File Manager uses the disk cache as an intermediate buffer when 
reading data from or writing it to the file system. When your application requests 
that data be read from a file, the File Manager looks for the data in the disk cache 
and transfers it to your application's data buffer if the data is found in the cache; 
otherwise, the File Manager reads the requested bytes from the disk and puts them in 
your data buffer. 

Note 

You can also read a continuous stream of characters or a line of 
characters from a file. In the first case, you ask the File Manager to read a 
specific nimiber of bytes: When that many have been read, or when the 
mark reaches the logical end-of-file, the read operation terminates. In the 
second case, called newline mode, the read operation terminates when 
either of the above conditions is met or when a specified character, the 
newline character, is read. The newline character is usually Return 
(ASCII code $0D), but it can be any character. Information about newline 
mode is associated with each access path to a file and can differ from 
one access path to another. See the chapter "File Manager" in this book 
for more iitifojnmation about newline mode. ♦ 

The Hierarchical File System 

The Macintosh Operatijfig System uses a method of organizing files called the 
hierarchical file system (HFS). In HFS, files are grouped into directories (also called 
folders), which themselves are grouped into other directories, as illustrated in 
Figure 1-4. The number listed for each directory is its directory ID. The directory ID 
is one component of a file system specification, as explained in the next section, 
"Identifying Files and Directories." 
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Figure 1-4 The Macintosh hierarchical file system 



MyVolume 



21 



26 



Fruits 



Nuts 















n 




27 



Vegetables 







35 




39 



Apples Melons Tropical Walnuts Empty Folder Red 



ODD 



2l 



Ackees Bananas Coconuts Guavas 



Tomatoes 



The Finder is responsible for managing the files and folders on the desktop. It works 
with the File Manager to n\aintain the organization of files and folders on a volume. The 
hierarchical relationship of folders within folders on the desktop corresponds directly to 
the hierarchical directory structure maintained on the volume. The volume is known as 
the root directory, and the folders are known as subdirectories, or simply directories. 

A volume appears on the desktop only after it has been mounted. Ejectable volumes 
(such as 3.5-inch floppy disks) are mounted when they're inserted into a disk drive; 
nonejectable volumes (such as those on hard disks) are mounted automatically at system 
startup. When a volume is mounted, the File Manager places information about the 
volume in a nonrelocatable block of memory called a volume control block (VCB). The 
number of volumeis that can be mounted at any time is liinited ovly by the number of 
drives attadhed and available memory. 

When a volume is inounted, the File Manager assigris a volume reference number by 
which you can refer to the volxMiie for as long as it remains mounted. You can also 
identify a volume by its volume name, a sequence of 1 to 27 printing characters, 
excluding colons (:). (The File Manager ignores case when comparing names but does 
recognize diacritical marl^s,) Whenever possible, though, you should use the volume 
reference number to avoid confusion between volumes with the same name. 

Note 

A volume reference number is valid only until the volume is 
unmoimted. If a single volume is moimted and then unmounted, the 
File Manager may assign it a different volume reference number when it 
is next moimted. ♦ 
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When an application ejects a 3.5-inch disk fron\ a drive, the File Manager places the 
volume offline. When a volume is offline, the volume control block is kept in memory 
and the volume reference number is still valid. If you make a File Manager call that 
specifies that volume, the File Manager presents the disk switch dialog box to the user. 
Figure 1-5 shows a sample disk switch dialog box. 

Figure 1-5 The disk switch dialog box 
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When the user drags a volume icon to the Trash, that volume is unmounted; the 
volume control block is released, and the volume is no longer known to the File 
Manager. In particular, the volume reference number previously assigned to the 
volume is no longer valid. 

Each subdirectory is located within a directory called its parent directory. Typically, the 
parent directory is specified by a parent directory ID, which is simply the directory ID of 
the parent directory. The File Manager assigns a Special parent directory ID to a volimne's 
root directory. This is primarily to permit a consistent method of identifying files and 
directories using the volume reference number, the parent directory ID, and the file or 
directory name. See the next section, "Identifying Files and Directories," for details. 

For the most part, your application does not need to be concerned about, or keep track 
of, the location of files in the file system hierarchy. Most of the files your application 
opens and saves are specified by the user or another application, and their location is 
provided to your application by either the Finder or the Standard File Package. One 
notable exception here concerns preferences files, which are typically stored in the 
Preferences folder in the currently active System Folder. See "Using a Preferences File" 
on page 1-36 for instructions on finding preferences files. 

Note 

In addition to files, folders, and volumes, a fourth type of object, namely 
aft alias, ihight appear oh the Finder desktop. An Alias is a special kind 
of file that represents another file, folder, or volume. The Finder and the 
Standard File Package automatically resolve aliases before passing files 
to your application, so you generally don't need to do anything with 
aliases. For more information on working with alias files, see the chapter 
"Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials and 
the chapter " Alias Manager" in this book. ♦ 
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identifying Files and Directories 



The hierarchical arrangement of files and directories allows you to identify a file or 
directory uniquely by providing just three pieces of information: its volume reference 
number, its parent directory ID, and its name within that parent directory. The system 
software lets you specify these three items together in a file system specification record, 
defined by the FSSpec data type: 



TYPE FSSpec 

RECORD 

vRefNum: 
par ID: 
name: 

END; 



= {file system specification) 

Integer; {volurae reference number) 

Longint; {directory ID of parent directory} 

Str63; {filename or directory name) 



The FSSpec record provides a simple and standard format for specifying files and 
directories. For example, the Standard File Package procedure StandardGetFile uses 
an FSSpec record to return information identifying a user-selected file or folder. You can 
pass that specification directly to any file-manipulation routines, such as FSpOpenDF 
and FSpDelete, that accept FSSpec records. In addition, the Alias Manager, Edition 
Manager, and Finder all use FSSpec records to specify files and directories. 



Using Files 

This section describes how to perform typical file operations using some of the services 
provided by the Standard File Package, the File Manager, the Finder, and other system 
software components. Figure 1-6 shows the typical appearance of an application's 
File menu. 



Figure 1-6 A typical File menu 
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Note that all the commands in this menu, except for the Quit and Page Setup commands, 
manipulate files. Your application's File menu should resemble the menu shown in 
Figure 1-6 as closely as possible. In general, whenever the user creates or manipulates 
information that is stored in a document, you need to implement all the commands 
shown in Figure 1-6. 

Note 

Some applications allow the user to create or edit information that is not 
stored in a document. In those cases, it is inappropriate to put the 
commands that create or manipulate that information in the File menu. 
Instead, group those commands together in a separate menu. ♦ 

Listing 1-1 shows one way to handle some of the typical commands in a File menu. Most 
of the techruques described in this section are illustrated by mear\s of definitions of the 
fimctions called in Listing 1-1. 

Listing 1-1 Handling Itie RIe menu commands 

PROCEDURE DoHandleFileCominand (menultem: Integer) ; 
VAR 

myErr : OSErr; 
BEGIN 

CASE menultem OF 



iNew: 






myErr : = 


DoNewCmd ; 


{create a new document) 


iOpen: 






myErr : = 


DoOpenCmd ; 


{open an existing document) 


iClose: 






myErr := 


DoCloseCmd; 


{close the current document) 


iSave: 






myErr : = 


DoSaveCmd; 


{save the current document) 


iSaveAs : 






myErr : = 


DoSaveAsCmd; 


{save document under new name) 


iRevert : 






myErr : = 


DoRe ve r t Cmd ; 


{revert to last saved version) 


OTHERWISE 







END; 
END; 

Your application should deactivate any menu commands that do not apply to the 
frontmost window. For example, if the frontmost window is not a docxmient window 
belonging to your application, then the Qose, Save, Save As, and Revert commands 
should be dimmed when the menu appears. Similarly, if the document in the frontmost 
window does belong to your application but contains data that has not changed since it 
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was last saved, then the Save menu command should be dinuned. See "Adjusting the 
File Menu" on page 1-37 for Retails on implementing this feature. The definitions of the 
application-defined functions iised in Listing 1-1 assume that this feature has been 
implemented. 

The techniques described in this chapter for manipulating files assume that you identify 
files and directories by using file system specification records. Because tiie routines that 
accept FSSpec records are not available on all versions of system software, you may 
need to test for the availability of those routines before actually calling any of them. See 
the next section, "Testing for File Management Routines," for details. 

Testing for File Management Routines 

To determine the availability of the routines that operate on FSSpec records, you can 
call the Gestalt function with the gestaltFSAt tr selector code, as illustrated in 
Listing 1-2. 

Listing 1-2 Testing for the availability of routines that operate on FSSpec records 



FUNCTION FSSpecRoutinesAvail: Boolean; 
VAR 

myErr; OSErr; {Gestalt result code) 

myFeature: Longlnt; {Gestalt response) 

BEGIN 

FSSpecRoutinesAvail := FALSE; 

IF gHaeGestalt THEN {if Gestalt is available) 

BEGIN 

myErr := Gestalt (gestaltFSAttr, myFeature); 
IF myErr - noErr THEN 

IF BTst (myFeature, gestaltHasFSSpecCalls) THEN 
FSSpecRoutinesAvail := TRUE; 

END; 

END; 

To use the procedures defined in the following sections to open and save files, you 
also need to make sure that the routines StandardGetFile and StandardPutFile 
are available. You can do this by passing Gestalt the gestal tStandardFileAttr 
selector and verifying that the bit gestaltStandardFileSS is set in the respor\se 
value. Also, before using the FindFolder function (as shown, for example, in 
Listiiig 1-10 on page 1-25), you should call the Ges t al t function with the 
gestaltFindFolderAttr selector and verify that the gestaltFindFolderPresent 
bit is set; this indicates that the FindFolder function is available. 
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If the routines that operate on FSSpec records are not available, you can use 
corresponding File Manager and Standard File Package routines. For example, if 
you cannot call-FSpOpenDF, you can call HOpenDF. That is, instead of writing 

myErr := FSpOpenDF {mySpec, fsCurPerm, myFile) ; 
you can write something like 

myErr := HOpenDF (my Vol , myDirlD, myName, fsCurPerm, myFile); 

The only difference is that the ray Spec parameter is replaced by three parameters 
specifying the volume reference number, the parent directory ID, and the filename. With 
ordy a few exceptions, all of the techniques presented in this chapter can be easily 
adapted to work with high-level HFS routines in place of the routines that work with 
FSSpec records^ 



Note 

One notable exception concerns the Standard File Package procedures 
SFGetFile and SFPutFile. The vRef Num field of the reply 
record passed to both these functions contains a working directory 
reference number, which encodes both the directory ID and the 
volume reference number. In general, yoii should avoid using this 
ntmtiber; instead you can turn* it into the corresponding directory ID and 
volimie reference number by calling the GetWDinf o function. See the 
chapter "FOe Manager" in tliis book for details on working directory 
reference numbers. ♦ 

Defining a Document Record 

When a user creates a new document or opens an existing document, your application 
displays the contents of the document in a window, which provides a standard interface 
for the user to view and possibly edit the doctmxent data. It is viseful for your application 
to define a document record, an application-specific data structure that contains 
information about the window, any controls in the window (such as scroll bars), and the 
file (if any) whose contents are displayed in the window. Listing 1-3 illustrates a sample 
document record for an application that handles text files. 



Listing 1 -3 A sample document record 



TYPE 

MyDocRecHnd = '^MyDocRecPtr ; 

MyDocRecPtr = '"MyDocRec; 

MyDocRec = . 
RECORD 

editRec: TEHandle; {handle to TextEdit record} 

vScrollBar: ControlHandle; {vertical scroll bar} 
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hScrollBar: 
f ileRefNiam: 
f ileFSSpec: 
windowDirty : 
END; 



Cont rolHandle ; 
Integer; 
FSSpec; 
Boolean; 



{horizontal scroll bar.} 
{ref num for window's file) 
{file's FSSpec) 
{has window data changed?) 



Some fields in the MyDocRec record hold information about the TextEdit record that 
contaiiis the window's text data. Other fields describe the horizontal and vertical scroll 
bars in the window. The my DocRec record also contains a field for the file reference 
number of the open file (if any) whose data is displayed in the window and a field for 
the file system specification that identifies that file. The file reference nimaber is needed 
when the application manipulates the open file (for example, when it reads data from or 
writes data to the file, and when it closes ti\e file). The FSSpec record is needed when a 
"safe-save" procedure is used to save data in a file. 

The last field of the MyDocRec data type is a Boolean value that indicates whether the 
contents of the document in the TextEdit record differ from the contents of the dociunent 
in the associated file. When your application first reads a file into the window, you 
should set this field to FALSE. Then, when any subsequent operations alter tiie contents 
of the document, you should set the field to TRUE. Your application can inspect this field 
whenever appropriate to determine if special processing is needed. For example, when 
the user closes a document window and the value of the windowDirty flag is TRUE, 
your application should ask the user whether to save the changed version of the 
document in the file. See Listing 1-16 (page 1-33) for details. 

To associate a document record with a particular window, you can simply set a handle to 
that record as the reference constant of the window (by using the Window Manager 
procedure SetWRef Con). Then you can retrieve the document record by calling the 
GetWRef Con function. Listing 1-15 illustrates this process. 



Creating a New File 

The user expects to be able to create a new document using the New command in the 
File menu. Listing 1-4 illustrates one way to handle the New menu command. 

Listing 1-4 Handling ttie New menu command 



FUNCTION DoNewCmd: OSErr; 
VAR 

myWindow: WindowPtr; {the new document window; ignored here) 
BEGIN 

{Create a new window and make it visible.} 
DoNewCmd := DoNewDocWindow(TRUE, myWindow); 
END; 
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I 



The DoNewCmd function simply calls the application-defined function DoNewDocWindow 
(shown in Listing 1-5). The first parameter to DoNewDocWindow determines whether the 
new window should be visible or not; the value TRUE indicates that the new window 
should be visible. If DoNewDocWindow completes successfully, it returns a window ^ 
pointer to the calling routine in the second parameter The DoNewCmd function ignores 
Ihat returned window pointer. 5- 

o 
2! 

Listing 1-5 Creating a new document window ® 

FUNCTION DoNewDocWindow (newDocument : Boolean; var myWindow: WindowPtr) : g 

a> 

OSErr; 3 
VAR - 

myData: MyDocRecHnd; {the window's data record} 

CONST 

rDocWindow = 1000; {resource ID of window template) 

BEGIN 

{Allocate a new window; see Window Mgr chapter for details.) 
myWindow := GetNewWindow( rDocWindow, NIL, WindowPtr ( -1 )) ; 
.IF myWindow = NIL THEN 
BEGIN 

DoNewDocWindow := MemError; 
Exit (DoNewDocWindow) ; 
END; 

{Allocate space for the window's data record.) 
myData := MyDocRecHnd (NewHandle (SizeOf (MyDocRec) )) ;" 
IF iTP^Data = NIL THEN 
BEGIN 

DoNewDocWindow -.= MemError; 
DisposeWindow (myWindow) ; 
Exit (DoNewDocWindow) ; 
END; 

MoveHHi (Handle (myData) ) ; {move the handle high) 

HLock (Handle (myData) ) ; {loclc the handle;) 

WITH myData'"'" DO {fill in window data) 

BEGIN 

editRec := TENew(gDestRect , gViewRect) ; 
vScroll := GetNewControl (rVScroll, myWindow); 
hScroll := GetNewControl (rHScroll, myWindow); 
fileRefNum := 0; {no file yet!) 

windowDirty := FALSE; 

IF (editRec = NIL) OR (vScroll = NIL) OR (hScroll = NIL) THEN 
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BEGIN 

DoNewDoc Window ;= memFullErr ; 
DisposeWindow(myWindow) ; 
DisposeControl(vScroll) ; 
DisposeControl(hScroll) ; 
TEDispose (editRec) ; 
DisposeHandle (myData) ; 
Exit (DoNewDocWindow) ; 
END; 

END; 

IF newDocuraent THEN {if new document, show it} 

ShowWindow( my Window) ; 

SetWRefCon(myWindow, Long I nt (myData) ) ; {link record to window} 
HUnlock (Handle (myData) ) ; {unlock the handle} 

DoNewDocWindow := noErr; 
END; 

Note that the DoNewDocWindow huiction does not actually create a new file. The reason 
for this is that it is usually better to wait until the user actually saves a new document 
before creating a file (mainly because the user might decide not to save the document). 
The DoNewDocWindow function creates a window, allocates a new document record, 
and fills out the fields of that record. However, it sets the f ileRef Num field of the 
document record to 0 to indicate that no file is currently associated with this window. 

Opening a File 

Your application might need to open a file in several different situations. For example, if 
the user laimches your application by double-clicking one of its document icons in the 
Finder, the Finder provides your application with information about the selected file (if 
your application receives high-level events, the Fmder sends it an Open Documents 
eyent). At that point, you want to create a new window for the document and read the 
document data from fhe file into the window. 

Your application also opens files after the user chooses the Open command in the File 
menu. In this case, you need to determine which file to open. You can use the Standard 
FUe Package to present a standard dialog box that allows the user to navigate the file 
system hierarchy (if necessary) and select a file of the appropriate type. Once you get the 
necessary ii\formation from ihe Standard File Package, you can then create a new 
window for the document and read the document data from the file into the window. 

As you can see, it iriakes sense to divide the process of opening a document into several 
different routines. You can have a routine that elicits a file selection from the user and 
another routine that creates a window and reads the file data into it. In the sample 
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listings given here, the function DoOpenCmd handles the interaction with the user and 
DoOpenFile reads a file into a new window. 

Listing 1-6 shows one way to handle the Open command in the File menu. It uses the 
Standard File Package routine StandardGetFile to determine which file the user 
wants to open. 



Usting 1-6 Handling the Open menu command 



FUNCTION DoOpenCmd: OSErr; 
VAR 

myReply: StandardFileReply ; {Standard File reply record} 
myTypes: SFTypeList; {types of files to display} 

my Err: OSErr; 
BEGIN 

myErr := noErr ; 

myTypes[0] := 'TEXT'; (display text files only} 

StandardGetFile(NIL, 1, myTypes, myReply); 
IF myReply. sf Good THEN 

myErr := DoOpenFile (myReply . sfFile) 
ELSE 

myErr := usrCanceledErr ; 
DoOpenCmd := myErr; 
END; 

The StandardGetFile procedure requires a list of file types to display in an Open 
dialog box, as in Figure 1-7. In this case, only text files are to be listed. 



Figure 1 -7 Ttie default Open dialog box 
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The user can scroll through the list of files m the current directory, change the current 
directory, select a file to open, or cancel the operation altogether. When the user clicks 
either the Cancel or the Open button, StandardGetFile fills out the Standard File 
reply record you pass to it which has this structure: 

TYPE StandardFileReply = 
RECORD 



s f Good : 


Boolean; 


{TRUE if user did not cancel} 


sf Replacing: 


Boolean; 


{TRUE if replacing file with same name} 


sfType: 


OSType ; 


{file type} 


sfFile: 


FSSpec; 


{selected item} 


sf Script : 


ScriptCode; 


{script of selected item's name} 


sf Flags: 


Integer; 


{Finder flags of selected item} 


sf IsFolder : 


Boolean; 


{selected item is a folder} 


sf IsVolume: 


Boolean; 


{selected item is a volume} 


sfReservedl : 


Longint ; 


{ reserved} 


sf Reserved2 : 


Integer; 


{reserved} 



END; 

In this situation, the relevant fields of the reply record are the sfGood and sfFile 
fields. If the user selects a file to open, the sf Good field is set to TRUE and the sfFile 
field contains an FSSpec record for the selected file. In Listing 1-6, the returned FSSpec 
record is passed directly to the application-defined function DoOpenFile. Listing 1-7 
illustrates a way to define the DoOpenFile function. 

Listing 1-7 Opening a file 



FUNCTION DoOpenFile (mySpec: FSSpec): OSErr; 
VAR 

my Window: WindowPtr; {window for file data} 

my Data: MyDocRecHnd; {handle to window data} 

myFileRefNum: Integer; {file reference number} 

my Err: OSErr; 
BfiGIN 

{Create a new window, but don't show it yet.} 
my Err := DoNewDocWindow( FALSE, myWindow) ; 
IF (myErr <> noErr) OR (myWindow = NIL) THEN 
BEGIN 

DoOpenFile := myErr; 
Exit (DoOpenFile) ; 
END; 

SetWTi tie (myWindow, mySpec.name) ; {set window's title} 
MySetWindowPos it ion (myWindow) ; {set window position} 
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{Open the file's data fork for reading and writing.}.. 
myErr := FSpOpenDF (mySpec, fsRdWrPerm, myFileRefNum) ; 
IF myErr <> noErr THEN 
BEGIN 

DisposeWindow(myWindow) ; 
DoOpenFile myErr; 
Exit (DoOpenFile) ; 
END; 

{Retrieve handle to window's data record.} 

myData := My DocRecHnd (GetWRef Con (my Window) ) ; 

rttyData"'^. fileRefNum := myFileRefNum; { save file information} 

myData^^ . f ileFSSpec := mySpec; 

myErr := DoReadFile (my Window ) ; {read in file data) 

ShowWindow(myWindow) ; (now show the window} 

DoOpenFile := myErr; 
END; 

This function is relatively simple because much of the real work is done by the two 
hmctions DoNewDocWindow and DoReadFile. The DoReadFile function is 
responsible for actually readii\g the file data from the disk into the TextEdit record 
associated with the document wmdow. See the next section, "Reading File Data," for a 
sample definition of DoReadFile. 

In Listing 1-7, the key step is the call to FSpOpenDF, which opens the data fork of the 
specified file. A file reference munber— which indicates an access path to the open file- 
is rehimed in the third parameter. As you can see, this reference number is saved in the 
document record, from where it can easUy be retrieved for future caUs to the FSRead 
and FSWr i t e functions. 

The second parameter in a call to the FSpOpenDF hmction specifies the access mode for 
opening the file. For each file, the File Manager maintains access mode information that 
determines what type of access is available. Most applications support one of two types 
of access: 

■ A single user is allowed to read from and write to a file. 

■ Multiple users are allowed to read bom a file, but no one can write to it. 
Your application can use the following constants to specify these types of access: 



CONST 

fsCurPenn = 0 

fsRdPerra = 1 

fsWrPerm = 2 

fsRdWrPerm = 3 

fsRdWrShPerm = 4 



Using Files 



{whatever permission is allowed} 

{read permission) 

{write permission) 
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To open a file with exclusive read/ write access, you cai\ specify f sRdWrPerrtu To open a 
file with read-only access, specify f sRdPerm. If you want to open a file and don't know 
or care which type of access is available, specify f sCurPerm. When you specify 
f sCurPerm, if no access paths are already open, the file is opened with exclusive read/ 
write access. If other access paths are already open, but they are read-only, another 
read-only path is opened. 

Reading File Data 



Once you have opened a £Qe, you can read data from it by calling the FSRead function. 
Generally you need to read data from a fUe when the user first opens a file or when the 
user reverts to the last saved version of a document. The DoReadFile function defined 
in Listing 1-8 illustrates how to use FSRead to read data from a file into a TextEdit 
record in either situation. 



Listing 1-8 Reading data from a file 



FXJNCTION E)oReadFile (myWindow: WindowPtr) 
VAR 



OSErr ; 



my Data: 
inyFile: 
my Length: 
inyText : 
myBuf f er : 
myErr : 
BEGIN 

my Data : - 



MyDocRecHnd; 
Integer ; 
Longint ; 
TEHandle; 
Ptr; 
OSErr ; 



{handle to a document record) 
{file reference number) 
{number of bytes to read from file) 
{handle to TextEdit record) 
{pointer to data buffer) 



MyDocRecHnd (GetWRef Con (myWindow) ) ; {get window's data) 



rayFile := myData'"'" . f ileRef Mum; 
myErr := SetFPos (myFile, fsFromStart, 0) 
IF myErr <> noErr THEN 
BEGIN 

DoReadFile := myErr; 
Exit (DoReadFile) ; 
END; 



{get file reference number) 
{set file mark at start} 



myErr := GetEOF (myFile, myLength) ; 
myBuf fer := NewPtr (my Length ) ; 
IF myBuf fer = NIL THEN 
BEGIN 

DoReadFile := MemError; 
Exit (DoReadFile) ; 
END; 



{get file length) 
{allocate a buffer} 
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myErr := FSRead (myFile , myLength, myBuf f er) ; {read data into buffer} 
IF (myErr = noErr) OR (myErr = eofErr) THEN 

ggQjjq {move data into TERec) 

HLock (Handle (myData'^'^. editRec) ) ; 

TESetText (myBuf fer, myLength, myData'"^ . editRec) ; 

myErr := noErr; 

HUnlock (Handle (myData"".editRec) ) ; 
END; ' 
DoReadFile := myErr; 
END; 

The DoReadFi le function takes one parameter specifying the window to read data into. 
This function first retrieves the handle to that window's document record and extracts 
the file's reference number from that record. Then DoReadFile calls the SetFPos 
hmction to set the file mark to the beginning of the file having that reference number. 
There is no need to check that myFile has a nonzero value, because SetFPos returns an 
error if you pass it an invahd file reference number. 

The second parameter to SetFPos specifies the file mark posifioning mode; it can 
contain one of the following values: 



CONST 

fsAtMark = 0 
fsFromStart = 1 
fsFromLEOF = 2 
f sFroroMark = 3 



{at current mark} 

{set mark relative to beginning of file} 
'{set mark relative to logical end-of-file} 
{set mark relative to current mark} 

If you specify fsAtMark, the mark is left wherever it's currently positioned, and the 
third parameter of SetFPos is ignored. The next three constants let you position the 
mark relative to either the beginning of the file, the logical end-of-file, or the current 
mark. If you specify one of these three constants, the third parameter contains the byte 
offset (either positive or negative) from the specified point. Here, the appropriate 
positioning mode is relative to the beginning of the file. 

If DoReadFile successfiiUy positioris the file mark, it next determines the number of 
bytes ii\ the file by calling the GetEOF function. The key step in the DoReadFile 
hmction is the call to FSRead, wMdi reads the specified nuniber of bytes from the file 
into the specified buffer. In this case, the data is read into a temporary buffer; then the 
data is moved into the TextEdit record associated with the file. The FSRead hmction 
rehims, in tiie ray Length parameter, the number of bytes achially read hrom die file. 



Writing File Data • ^ 

Generally your appUcation writes data to a file in response to the File menu commands 
Save or Save As. However, yovur application might also incorporate a scheme that 
autbmaticaUy saves all open documents to disk every few minutes. It tiierefore makes 
sense to isolate \he routines that handle the menu commands firom \he routines that 
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handle the actual writing of data tq disk. This section shows how to write the data stored 
in a TextEdit record to a file. See "Saving a File" on page 1-26 for instructions on 
handling the Save and Save As menu commands. 

It is very easy to write data from a specified buffer into a specified file. You simply 
position the file mark at the begirming of the file (using S6tFPos), write the data into 
the file (using FSWri te), and then resize the file to the number of bytes actually written 
(using SetEOF), Listing 1-9 illustrates this sequence. 



Listing 1 -9 Writing data into a file 



FUNCTION DoWriteData (myWindow: WindowPtr; myTemp: integer) : OSErr; 
VAR 

MyDocRecHnd; {handle to a document record} 

Longint; {number of bytes to write to file} 

TEHandle; (handle to TextEdit record} 

Handle; (handle to actual text in TERec} 

Integer; {volume reference number of myFile} 
OSErr; 



myData: 
my Length: 
my Text : 
myBuf f er : 
my Vol : 
myErr : 
BEGIN 

myData : = 



MyDocRecHnd (GetWRefCon (myWindow) ) 



myText : = myData^ . editRec ; 



(get window's data record} 
{get TERec} 



myBuf fer 


:= myText"^^ .hText ; 




{get text buffer} 


my Length 


:= myText^'" . teLength; 




(get text buffer size} 


myErr : = 


SetFPos (myTemp, f sFromStart , 


0); 


{set file mark at start} . 


IF myErr 


= noErr THEN 




(write buffer into file} 


myErr 


:= FSWrite (myTemp, myLength, 


myBuf fer ^) ; 


IF myErr 


= noErr THEN 




(adjust file size} 


myErr 


:= SetEOF (myTemp, rayLength) ; 






IF myErr 


= noErr THEN 




{find volume file is on} 


myErr 


:= GetVRefNum( myTemp, myVol) 


; 




IF myErr 


= noErr THEN 




{flush volume} 


myErr 


:= FlushVoKNIL, myVpl).; 






IF myErr 


= noErr THEN 




{show file is up to date} 



myData^'" -windowDirty := FALSE; 
DoWriteData := myErr; 
END; 



The DoWriteData function first retrieves the TextEdit record attached to the specified 
window and extracts the address and length of the actual text buffer from that record. 
Then it calls SetFPos, FSWrite, and SetEOF as just explained. Finally, DoWriteData 
determines the volume containing the file (using the GetVRef Mum function) and flushes 
that volume (using the FlushVol function). This is necessary to ensure that both the 
file's data and the file's catalog entry are updated. 
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Notice that the DoWr i t eData function takes a second parameter, myTemp, which should 
be the fOe reference number of a temporary file, not the file reference number of the file 
associated with the window whose data you want to write. If you pass the reference 
number of the fUe associated with the window, you risk corrupting the fOe, because the 
existing file data is overwritten when you position the file mark at the beginning of the 
file and call FSWritie. If FSWr ite does not complete successfully, it is very likely that 
the file on disk does not contain the correct document data. 
To avoid corrupting the file containing the saved version of a document, always call 3 
DoWriteData specifying the file reference number of some new, temporary file. Then, g; 
when DoWr i t eData completes successhiUy, you can call \he FSpExchangeFi les | 
hmction to swap the contents of the temporary fUe and the existing file. Listing 1-10 | 
iUustrates how to update a file on disk safely; it shows a sequence of updating, © 
renaming, saving, and deleting files that preserves the contents of the existing file until 
the new version is safely recorded. 



I 



Listing 1-10 Updating a file safely 



FUNCTION DoWriteFile (myWindow) ; OSErr; 
VAR 

myData : MyDocRecHnd ; 

myFSpec : FSSpec ; 

myTSpec : FSSpec ; 

iriyTime: Longint; 

myName: Str255; 

myTemp: Integer; 

myVRef: Integer; 

myDirlD: Longint; 

myErr: OSErr; 



(handle to window's document record) 
{FSSpec for file to update] 
{FSSpec for temporary file) 
{current time; for temporary filename) 
{name of temporary file) 

(file reference number of temporary file) 
{volume reference number of temporary file) 
{directory ID of temporary file) 



BEGIN 

myData := My DocRecHnd(GetWRef Con (myWindow) ); {get that window's data) 

myData--. fileFSSpec; {get FSSpec for existing file) 



itiyFSpec 



GetDateTime(inyTime) ; 
NumToStr ing (myTime , myName ) ; 



{create a temporary filename) 



{Find the temporary folder on file's volume; create it if necessary.) 
myErr := FindFolder (myFSpec. vRefNum, kTemporaryFolderType, 

kCreateFolder, myVRef, rayDirlD) ; 
IF myErr = noErr THEN (niake an FSSpec for temp file) 

myErr := FSMakeFSSpec (nryVRef , myDirlD, myName, myTSpec); 
IF (myErr = noErr) OR {myErr - fnfErr) THEN{create a temporary file) 

myErr := FSpCr eat e( myTSpec, 'trsh', 'trsh', smSystemScript) ; 
IF myErr noErr THEN (open the newly created file) 
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myErr := FSpOpenDF (myTSpec, fsRdWrPerm, myTemp) ; 
IF myErr = noErr THEN {write data to the data fork) 

myErr := DoWriteData (myWindow, myTemp); 
IF myErr = noErr THEN {close the temporary file} 

myErr := FSClose (ray Temp) ; 
IF myErr = noErr THEN {swap data in the two files} 

myErr := FSpExchangeFiles (myTSpec , myFSpec) ; 
IF myErr = noErr THEN {delete the temporary file} 

myErr := FSpDelete (myTSpec) ; 
DoWriteFile := myErr; 
END; 

The essential idea behind this "safe-save" process is to save the data in memory into a 
new file and then to exchange the contents of the nev^ file and the old version of the file 
by calling FSpExchangeFiles. The FSpExchangeFiles function does not move the 
data on the volume; it merely changes the information in the volume's catalog file and, if 
the files are open, in their file control blocks (FCBs). The catalog entry for a file contains 

■ fields that describe the physical data, such as the first allocation block, physical end, 
^ . and logical end of both the resource and data forks 

■ fields that describe the file within the file system, such as file ID and parent 
directory ID 

Fields that describe the data remain with the data; fields that describe the file remain 
with the file. The creation date remains with the file; the modification date remains with 
the data. (For a more complete description of the FSpExchangeFiles function, see the 
chapter "File Manager" in this book.) 

Saving a File 

There are several ways for a user to indicate that the current contents of a document 
should be saved (that is, written to disk). The user can choose the File menu commands 
Save or Save As, or the user can cHck the Save button in a dialog box that you display 
when the user attempts to close a "dirty" document (that is, a document whose contents 
have changed since the last time it was saved), Y&u can handle the Save menu command 
quite easily, as illustrated in Listing HI. 

Listing 1-11 Handling the Save menu command 



FUNCTION DoSaveCmd: OSErr; 
VAR 

myWindow: WindowPtr; {pointer to the front window} 

myData: MyDocRecHnd; {handle to a document record) 

myErr: OSErr; 
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BEGIN 

myWindow := FrontWindow; (get front window and its data) 

myData := MyDocRecHnd (GetWRef Con (myWindow) ) ; 

IF myData"-". fileRefNum <> 0 THEN {if window has a file already) 

myErr := DoWriteFile (myWindow) ; {then write contents to disk) 
ELSE 

myErr := DoSaveAsCmd; {else ask for a filename) 

DoSaveCmd := myErr; 
END; 

The DoSaveCmd function simply checks whether the frontmost window is already 
associated with a file. If so, then DoSaveCmd calls DoWriteFile to write the data to 
disk (using the "safe-save" process illustrated in the previous section). Otherwise, if no 
file exists for that window, DoSaveCmd calls DoSaveAsCmd. Listing 1-12 shows a way to 
define the DoSaveAsCmd function. 

Listing 1-12 Handling the Save As menu command 



FUNCTION DoSaveAsCmd: OSErr; 
VAR ' ' 

myWindow: WindowPtr; {pointer to the front window) 

myData: MyDocRecHnd; {handle to a document record) 

myReply : StandardFileReply ; 

myFile: Integer; {file reference number) 

myErr: OSErr; 
BEGIN 

myWindow := FrontWindow; {get front window and its data) 

myData := MyDocRecHnd (GetWRef Con (myWindow) ) ; 
myErr := noErr; 

StandardPutFile( 'Save as:.' , 'Untitled*, myReply); 
IF myReply. sf Good THEN {user saves file) 

BEGIN 

IF NOT myReply.sf Replacing THEN 

myErr := FSpCreate (myReply . sf File, 'MYAP*, 'TEXT', 

smSystemScript) ; 

IF myErr <> noErr THEN 

Exit (DoSaveAsCmd) ; 
myData''^. fileFSSpec := myReply . sf File; 

IF myData" ".fileRefNum <> 0 THEN {if window already has a file) 
myErr : = FSClose (myData'^'' . fileRefNum) ; {close it) 
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{Create document's resource fork and copy Finder resources to it.} 
FSpCreateResFilednyData^'". f ileFSSpec, 'MYAP' , 'TEXT* , 
smSystemScript) ; 

inyErr := ResError; 

IF myErr - noErr THEN 

myFile := FSpOpenResFile {myData'"'" . f ileFSSpec, f sRdWrPerm) ; 
IF myFile > 0 THEN {copy Finder resources} 

myErr := DoCopyResource ( • STR -16396, gAppsResFile, myFile) 
ELSE 

myErr := ResError; 
IF myErr = noErr THEN 

myErr := FSClose (myFile) ; {close the resource fork} 

{Open data fork and leave it open.} 
IF myErr = noErr THEN 

myErr := FSpOpenDF (myData^^ . f ileFSSpec, fsRdWrPerm, myFile) ; 
IF myErr = noErr THEN 

BEGIN 

inyData'^^ . f ileRefNum := myFile; 
SetWTitle (niyWindow, myReply . sf File .name) ; 
myErr := DoWriteFile (my Window ) ; 
END; 

DoSaveAsCmd : = myErr; 
END; 

END; 

The StandardPutFile procedure is similar to the StandardGetFile procedure 
discussed earlier in this chapter. It manages the user interface for the default Save dialog 
^ box, illustrated in Figure 1-8. 



Rgure 1-8 The default Save dialog box 
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If the user clicks the New Folder button, the Standard File Package presents a subsidiary 
dialog box like the one shown in Figure 1-9. 

Figure 1-9 The new folder dialog box 
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If the user asks to save a file with a name that already exists at the specified location, 
the Standard File Package displays a subsidiary dialog box, like the one shown in 
Figure 1-10, to verify that the new file should replace the existing file. 

Figure 1-10 The name conflict dialog box 
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Note in Listing 1-12 that if the user is not replacing an existing file, the DoSaveAsCmd 
function creates a new file and records the new FSSpec record in the window's 
document record. Otherwise, if the user is replacing an existing file, DoSaveAsCmd 
simply records, in the window's document record, the FSSpec record returned by 
StandardGetFile. 

When DoSaveAsCmd creates a new file, it also copies a resource from your application's 
resource fork to the resource fork of the newly created file. This resource (with ID 
-16396) identifies the name of your application. (For more details about this resoiurce, 
see the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials.) ' 
The DoSaveAsCmd function calls the application-defined routine DoCopyRe source. 
Listing 1-13 shows a simple way to define the DoCopyResource function. 
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Listing 1-13 Copying a resource from one resource fork to another 



FUNCTION DoCopy Resource (theType: ResType; thelD: Integer; 

source: Integer; dest: Integer) : OSErr; 

VAR 

ntyHandle: Handle; - - {handle to resource to copy} 

itiyName: Str255; ' {name of resource to copy) 

myType: ResType; {ignored; used for GetResInfo) 

mylD: Integer; {ignored; used for GetResInfo} 

BEGIN 

UseResFile (source) ; {set the source resource file} 

myHandle := Get Resource (theType, thelD) ; {open the source resource) 
IF myHandle <> NIL THEN 
BEGIN 

GetResInfo (myHandle, mylD, myType, myName) ; {get resource name} 

DetachResource (myHandle) ; {detach resource) 

UseResFile (dest) ; (set destination resource file) 

AddResource (myHandle, theType, thelD, myName); 

IF ResError = noErr THEN 

WriteResource (myHandle) ; {write resource data} 

END; 

DoCopyResource := ResError; {return result code) 

ReleaseResource (myHandle) ; 
END; 

See the chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox for 
details about the routines used in Listing 1-13. 



Reverting to a Save(J File 

Many applications that marupulate files provide a menu contmand that allows the user 
to revert to the last saved version of a document. The technique for handling diis 
command is relatively simple. First you should display a dialog box asking whedier to 
revert to the last saved version of the file, as illustrated in Figure 1-11, 

Figure 1-11 A Revert to Saved dialog box 
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If the user clicks the Cancel button, nothing should happen to the current document. If, 
however, the user confirms the menu conunand by clicking OK, you just need to call 
DoReadFile to read the disk version of the file back into the v/indow. Listing 1-14 
illustrates how to implement a Revert to Saved menu command. 



Listing 1-14 Handling the Revert to Saved menu command 



FUNCTION DoRevertCmd: OSErr; 
VAR 



myWindow; 

my Data : 

inyFile: 

myName : 

myDialog ; 

my I tern: 

my Port : 
CONST 

kRevertDialog = 128; 
BEGIN 

myWindow := FrontWindow; 



WindowPtr ; 

MyDocRecHnd;, 

Integer; 

Str255; 

DialogPtr; 

Integer; 

Graf Ptr ; 



{window for file data} 
{handle to window data} 
{file reference number} 
{file's name} 

{pointer to modal dialog box} 
{item selected in modal dialog} 
{the original graphics port} 

{resource ID of Revert to Saved dialog} 



{get pointer to front window} 
{get handle to window's data record} 
myData : = MyDocRecHnd (GetWRef Con (myWindow) ) ; 
GetWTi tie (myWindow, myName); {get file's name} 

ParamText (myName, ' ' , ' ' , ' ' ) ; 

myDialog := GetNewDialog (kRevertDialog, NIL, WindowPtr ( -1) ) ; 
GetPort (myPort ) ; 
SetPort (myDialog) ; 



REPEAT 

ModalDialog (NIL, myltem) ; 
UNTIL (myltem = iOK) OR (rayltem = iCancel) ; 



pisposeDialog (myDialog) ; 
SetPort (my Port) ; 



{restore previous grafPort) 



IF myltem = iOK THEN 

DoRevertCmd := DoReadFile (myWindow) ; 
ELSE 

DoRevertCmd := noErr; 

END; 

The DoRevertCmd function retrieves the document record handle horn the frontmost 
v^indow's reference constant field and then gets the window's title (which is also the 
name of the file) and inserts it into a modal dialog box. 
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If the user clicks the OK button, DoRever tCmd calls the DoReadFile function to read 
the data from the file into the window. Otherwise, DoRevertCmd simply exits without 
changing the data in the window. 

Closing a File 

In most cases, your application closes a file after a user clicks in a window's close box or 
chooses the Close command in the File menu. The Close menu command should be 
active only when there is actually an active window on the desktop. If there is an active 
window, you need to determine whether it belongs to your application; if so, you need to 
handle dialog windows and document windows differently, as illustrated in Listing 1-15. 

Listing 1-15 Handling the Close menu command 

FUNCTION DoCloseCmd: OSErr; 
VAR 

my Window: WindowPtr; 
myData: MyDocRecHnd; 
my Err: OSErr; 
BEGIN 

my Err := FALSE; 

myWindow := FrontWindow; {get window to be closed} 

CASE MyGetWindowType (myWindow) OF 
kDAWindow: 

CloseDeskAcc (WindowPeek (myWindow) ^ . windowKind) ; 
kMyModelessDialog : 

HideWindow (myWindow) ; {for dialogs, hide the window) 

kMy DocW i ndow : 

BEGIN 

myData := MyDocRecHnd (GetWRe f Con (myWindow) ) ; 
myErr := DoCloseFile (myData) ; 
IF myErr = ndErt THEN 

DisposeWi ndow (my Window) ; 

END; 
OTHERWISE 

END; 

DpCloseCmd := myErr; 
END; 

The DoCloseCmd function determines the type of the frontmost window by calling the 
application-defined function MyGetWindowType. (See the chapter "Window Manager" 
in Inside Macintosh: Macintosh Toolbox Essentials for a definition of MyGetWindowType.) If 
the window to be closed is a window belonging to a desk accessory, DoCloseCmd closes 
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the desk accessory. If the window to be closed is a dialog window, this procedure just 
hides the window. If the window to be closed is a document window, DoCloseCmd 
retrieves its document record handle and calls both DoCloseFi le (defined in 
Listing 1-16) and DisposeWindow. Before you close the file associated with a 
window, you should check whether the contents of the window have changed since 
the last time the document was saved. If so, you should ask the user whether to save 
those changes. Listing 1-16 illustrates one way to do this. 

Listing 1-16 Closing a file 



FUNCTION DoCloseFile (myData: MyDocRecHnd) : OSErr; 
VAR . 

myErr: OSErr; 

myDialog: DialogPtr; {pointer to modal dialog box} 

myltem: Integer; {item selected in alert box} 

myPort: GrafPtr; {the original graphics port) 

CONST 

kSaveChangesDialog = 129; (resource of Save changes dialog} 

BEGIN 

IF myData"". windowDirty THEN {see whether window is dirty} 
BEGIN 

myltem := CautionAlert (kSaveChangesDialog , NIL); 
IF myltem = iCancel THEN{user clicked Cancel} 
BEGIN 

DoCloseFile := usrCanceledErr ; 
Exit (DoCloseFile) ; 
END; 

IF myltem = iSave THEN 
myErr := DoSaveCmd; 

END; 

IF myData"". fileRefNum <> 0 THEN 
BEGIN 

myErr := FSClose (myData"" . fileRefNum) ; 
IF myErr = noErr THEN 
BEGIN 

myErr := FlushVol (NIL, myData"" . fileFSSpec ivRefNum) ; 
myData" ^.fileRefNum := 0; {clear the file reference number} 
END; 

END; 

{Dispose of TextEdit record and controls here (code omitted).} 
DisposeHandle (Handle (myData) ) ; {dispose of document record} 

DoCloseFile := myErr; 
END; 
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If the document is an existing file that has not been changed since it was last saved, your 
application can simply call the FSClose function. This routine writes to disk any 
imwritten data remaining in the volume buffer. The FSClose function also updates the 
information maintained on the volume for that file and removes the access path. The 
information about the file is not actually written to the disk, however, until the volume is 
flushed, ejected, or urmiounted. To keep the file information current, it's a good idea to 
follow each call to FSClose with a call to the FlushVol function. 

If the contents of an existing file have been changed, or if a new file is being closed for 
the first time, your application can call the Dialog Manager routine CautionAlert 
(specifying a resource ID of an ' ALRT ' template) to ask the user whether or not to save 
the changes. If the user decides not to save the file, you can just call FSClose and 
dispose of the window. Otherwise, DoCloseFile calls the DoSaveCmd function to save 
the file to disk. 

Opening Files at Application Startup Time 

A user often launches your application by double-clicking one of its docunient icons or 
by selecting one or more doctiment icons and choosing the Open command in the 
Finder's File menu. In these cases, your application needs to determine which files the 
user selected so that it can open each one and display its contents in a window. There are 
two ways in which your application can determine this. 

If the user opens a file from the Finder and if your application supports high-level 
events, the Finder sends it an Open Documents event. Your application then needs to 
determine which file or files to open and react accordingly. For a complete description of 
how to process the Open Documents event, see the chapter "Apple Event Manager" in 
Inside Macintosh: Inter application Communication, 

IMPORTANT 

If at all possible, your application should support high-level events. You 
should use the techniques illustrated in this section only if your 
application doesn't support high-level events. ▲ 

If your application does not support high-level events, you need to ask the Finder at 
application launch time whether or not the user launched the application by selecting 
some documents. You can do this by calling the Count AppFi les procedure and seeing 
whether the count of files is 1 or more. Then you can call the procedures GetAppFiles 
and Clr AppFi les to retrieve the information about the selected files. The technique is 
illustrated in Listing 1-17. 

The Count AppFi les procedure determines how many files, if any, the user selected at 
application startup time. If the value of the myNum parameter is nonzero, then my Job 
contains a value that indicates whether the files were selected for opening or printing. 
Currently, my Job can have one of two values: 

CONST 

appOpen = 0 ; { open the document ( s ) } 
appPrint = 1; {print the document(s)} 
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Listing 1-17 Opening files at application launch time 



PROCEDURE DoInitFiles; 
VAR 

myNum: Integer; 
my Job: Integer; 
index: Integer; 
myFile: AppFile; 
mySpec: FSSpec; 
myErr: OSErr; 
BEGIN 

CountAppFiles {myJob, myNum) , 
IF myNum > 0 THEN 

IF myJob = appOpen THEN 

FOR index := 1 TO myNum DO 
BEGIN 

GetAppFiles (index, myFile); {get file info from Finder} 
myErr := FSMakeFSSpec (myFile . vRefNum, 0, myFile . f Name, 

mySpec) ; {make an FSSpec to hold info} 
myErr := DoOpenFile (mySpec) ; {read in file's data} 
ClrAppFiles ( index) ; {show we've got the info} 

END; 



{number of files to be opened or printed} 
{open or print the files?} 
{index of current file} 
{file info} 

{file system specification} 



{user selected some files} 
{files are to be opened} 



END; 



In Listing 1-17, if the files are to be opened, then Dolnit Fi les obtains information 
about them by calling the GetAppFi les procedure for each one. The Get AppFiles 
procedure returns the information in a record of type AppFile. 



TYPE AppFile 
RECORD 

vRefNum: 
fType: 
versNum : 
fNcime : 
END; 



Integer; {working directory reference number} 

OSType; {file type} 

Integer; {version number; ignored} 

Str255; -{filename} 



Because the hinction DoOpenFile takes an FSSpec record as a parameter, 
DoInitFiles next converts the information returned in the myFile parameter into an 
FSSpec record, using FSMakeFSSpec. Then DoInitFiles calls DoOpenFile to read 
the file data and C 1 r AppF i 1 e s to let the Finder know that it has processed the 
information for that file. 
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Note 

The vRef Nvuna field of an AppFile record does not contain a volume 
reference number; instead it contains a working directory reference 
number, which encodes both the volume reference number and the 
parent directory ID. (That's why the second parameter passed to 
FSMakeFSSpec in Listing 1-17 is 0.) ♦ 



Using a Preferences File 



Many applications allow the user to alter various settings that control the operation or 
cor\figuration of the application. For example, your application might allow the user to 
specify the size and placement of any new windows or the default font used to display 
text in those windows. You can create a preferences file in which to record user 
preferences, and your application can retrieve that file whenever it is launched. 

In deciding how to structtu:e your preferences file, it is important to distinguish 
document-specific settings from application-specific settings. Some user-specifiable 
settings affect only a particular document. For example, the user might have changed the 
text font Ln a particular window. When you save the text in the window, you also want to 
save the current font setting. Generally you can do this by storing the font name in a 
resource in the document file's resource fork. Then, when the user opens that document 
again, you check for the presence of such a resource, retrieve the information stored in it, 
and set the document font accordingly. 

Some settings, such as a default text font, are not specific to a particular document. You 
might store such settings in the application's resource fork, but generally it is better to 
store them in a separate preferences file. The main reason for this is to avoid problems 
that can arise if an application is located on a server volume. If preferences are stored in 
resources in the application's resource fork, those preferences apply to all users 
executing that application. Worse yet, the resoiurces can become corrupted if several 
different users attempt to alter the settings at the same time. 

Hius, it is best to store application-specific settings in a preferences file. The Operating 
System provides a special folder in the System Folder, called Preferences, where you can 
store that file. Listing 1-18 illustrates a way to open your application's preferences file. 



Listing 1-18 Opening a preferences file 



PROCEDURE DoGetPref erences; 
VAR 

my Err: OSErr; 

myVRef : Integer; {volume ref num of Preferences folder} 

myDirlD: Longint; {dir ID of Preferences folder} 

mySpec: FSSpec; {FSSpec for the preferences file} 

myName: Str255; {name of the application} 

myRef : Integer; {ref num of app's resource file; ignored} 

myHand: Handle; {handle to Finder information; ignored} 

myRef Num: Integer; {file reference number} 
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kPrefID = 128; {resource ID of STR# with filename) 

BEGIN 

{Determine the name of the preferences file.} 
GetlndString {myName, kPrefID, 1) ; 

{Find the Preferences folder in the System Folder.} 

myErr := FindFolder (kOnSystemDisk, kPref erencesFolderType, 

kOontCreateFolder, rayVRef, myDirlD) ; 
IF myErr = noErr THEN 

myErr := FSMakeFSSpec (myVRef , myDirlD, myName, mySpec); 
IF myErr = noErr THEN 

myRefNum := FSpOpenResFile (mySpec , f sCurPerm) ; 

{Read your preference settings here.} 

CloseResFile (myRefNum) ; 
END; 

The DoGetPref erences procedure first determines the name of the preferences file it is 
to open and read. To allow easy localization, you should store the name in a resource of 
type ' STR# * in your application's resource file. The DoGetPref erences procedure 
assumes that the name is stored as the first string in the resource having ID kPref ID. 

The technique shown here assumes that your preference settings can all be stored in 
resources. As a result. Listing 1-18 calls the Resource Manager function FSpOpenResFile 
to open the resource fork of your preferences file. See the chapter "Resource Manager" in 
Inside Macintosh: More Macintosh Toolbox for complete details on opeiung resource files and 
reading resources from them. 

Adjusting the File Menu • 

Your application should dim any File menu commands that are not available at the time 
the user pulls down the File menu. For example^ if your application does not yet have a 
document window open, then the Save, Save As, and Revert commands should be 
dimmed. You can adjust the File menu easily using the technique shown in Listing 1-19. 



Listing 1-19 Adjusting the File menu 



PROCEDURE DoAdjustFileMenu; 
VAR 

myWindow : WindowPtr ; 
my Menu : MenuHandl e ; 

myData : MyDocRecHnd ? 



{handle to window data} 
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BEGIN 

myV/indow := FrontWindow; 
IF myWindow = NIL THEN 
BEGIN 

myMenu := GetMHandle (mFile) ; 

DisableItein(myMenu, iSave) ; {disable Save) 

Disableltem (myMenu, iSaveAs) ; {disable Save As} 
Disableltem (myMenu, iRevert) ; {disable Revert} 
DisableItem(myMenu, iClose) ; {disable Close} 

END 

ELSE IF MyGetWindowType (myWindow) = kMyDocWindow THEN 
BEGIN 

myData := My DocRecHiid(Ge tWRef Con (myWindow) ) ; 
myMenu := GetMHandle (mFile) ; 

Enablel tern (myMenu, iSaveAs) ; {enable Save As} 

Enablel tern (myMenu, iCIose) ; {enable Close} 



IF myData^". windowDirty THEN 
BEGIN 

Enableltem (myMenu, iSave) ; {enable Save} 

Enablel tern (myMenu, iRevert); {enable Revert} 

END 
ELSE 

BEGIN 

DisableItem(myMenu, iSave) ; {disable Save} 

Disableltem (myMenu,' iRevert); {disable Revert} 
END; 

END; 

END; 

Your application should call DoAdjustFileMenu whenever it receives a mouse-down 
event in the menu bar. (No doubt you want to include code appropriate for enabling and 
disabling other menu items too.) See the chapter "Menu Manager" in Inside Macintosh: 
Macintosh toolbox Essentials for details on the menu enabling and disabling procedures 
used in Listing 1-19. 



File Manag ement Reference 

This section describes the data structures and routines used in this chapter to illustrate 
basic file management operations. The section "Data Structures" shows the Pascal data 
structures for the file system specification record and the standard file reply record. The 
sections that follow describe the Standard File Package routines for opening and saving 
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documents and the File Manager routines for accessing files, manipulating files and 
directories, accessing volumes, and getting information about documents to be opened 
when your application is launched. 

For a description of other file-related data structures and routines, see the chapters "File 
Manager" and "Standard File Package" in this book. 



Data Structures 



This section describes the data structures that your application can use to exchange 
information with the File Manager and the Standard File Package. The techniques 
described in this chapter use file system specification records and standard file reply 
records. 



File System Specification Record 



The file system specification record for files and directories is defined by the FSSpec 
data type. 

TYPE FSSpec = (file system specification) 

RECORD 

vRefNum: Integer; {volume reference number] 
parlD: Longlnt; {directory ID of parent directory) 

name: Str63; {filename or directory name) 

END; 

Field descriptions 

vRef Num The volume reference number of the volume contairung the 

specified file or directory: 
par ID The directory ID of the directory contairung the specified file 

or directory. 

name The name of the specified file or directory. 



Standard File Reply Records 



The procedures StandardGetFile and StandardPutFile both return information 
to your application using a standard file reply record, which is defined by the 
StandardFileReply data type. The reply record identifies selected files with a file 
system specification record, which you can pass directly to many of the File Manager 
hmctions described in the sections that follow. The reply record also contains fields that 
support several Finder features. 



File Management Reference 1*39 

TIVO-408420 



CHAPTER 1 



Introduction to File Management 



TYPE StandardFileReply = 
RECORD 

sfGood: Boolean; 

sf Replacing : Boolean ; 

sfType: OSType; 

sfFile: FSSpec; 

sf Script: ScriptCode; 

sf Flags: Integer; 

sf IsFolder: Boolean; 

sf IsVolume: Boolean; 

sfReservedl: Longint; 

sf Reserved2 : Integer; 
END; 



Field descriptions 

sfGood 



sfReplacing 



sfType 



sfFile 



sfScript 



{TRUE if user did not cancel} 

{TRUE if replacing file with same name} 

{file type} 

{selected file, folder, or volume} 

{script of file, folder, or volume name} 

{Finder flags of selected item} 

{selected item is a folder} 

{selected item is a volume} 

{reserved} 

{reserved} 



Reports whether the reply record is valid. The vahie is TRUE after 
the user clicks Save or Open; FALSE after the user dicks Cancel 
When the user has completed the dialog box, the other fields in the 
reply record are valid only if the s f Good field contains TRUE. 
Reports whether a file to be saved replaces an existing file of 
the same name. This field is valid only after a call to the 
StandardPutFile or CustomPut File procedure. When 
the user assigns a name that duplicates that of an existing file, 
the Standard File Package asks for verification by displaying a 
subsidiary dialog box (illustrated in Figure 1-10). If the user 
verifies the name, the Standard File Package sets the s f Replacing 
field to TRUE and returns to your application; if the user cancels 
the overwriting of the file, the Standard File Package returns 
to the main dialog box. If the name does not conflict with an 
existing name, the Standard File Package sets the field to FALSE 
and retun\s. 

Contains the file type of the selected file. (File types are described in 
the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox 
Essentials.) Only StandardGetFile and CustomGetFile return a 
file type in this field. 

Describes the selected file, folder, or volume with a file system 
specification record, which contair\s a volume ref ereiice number, 
parent directory ID, arid name. (See the chapter "File Manager" in 
this book for a complete description of the file system specification 
reconi.) If the selected item is an alias for another item, the Standard 
File Package resolves the alias and places the file system 
specification record for the target in the sfFile field when the user 
completes the dialog box. If the selected file is a stationery pad, the 
reply record describes ttie file itself, not a copy of the file. 
Identifies the script in which the name of the document is to be 
displayed. (This information is used by the Finder and by the 
Standard File Package.) A script code of smSystemScr ipt (-1) 
represents the default system script. 
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sfFlags 



sf IsFolder 



sf IsVoliime 



sfReservedl 
sf Reserved2 



Contains the Finder flags from the Finder information record in the 
catalog entry for the selected file. (See the chapter "Finder Interface" 
in Inside Macintosh: Macintosh Toolbox Essentials for a description of 
the Finder flags.) This field is returned only by StandardGetFile 
and CustomGetFile. If your application supports stationery, it 
should check the stationery bit in the Finder flags to determine 
whether to treat the selected file as stationery. Unlike the Finder, the 
Standard File Package does not automatically create a doomrient 
from a stationery pad and pass your application the new document. 
If the user opens a stationery document from within an application 
that does not support stationery, the Standard File Package displays 
a dialog box warning the user that the master copy is being opened. 

Reports whether the selected item is a folder (TRUE) or a file or 
volume (false). This field is meaningful only dtuing the execution 
of a dialog hook function. 

Reports whether the selected item is a voluii\e (TRUE) or a file or 
folder (false). This field is mearungful only during the execution 
of a dialog hook function. 

Reserved. 

Reserved. 



Application Files Records 



The GetAppFiles procedure returns iiiformation about files opened at application 
laimch time in an application files record, defined by flie AppFile data type: 



TYPE AppFile 
RECORD 

vRefNum: 

fType: 

versNum: 

fName: 
END; 



Integer; {working directory reference number} 

OSType; {file type} 

Integer; (version number; ignored} 

Str255; {filename} 



Field descriptions 

vRefNum 

fType 

versNum 

fName 



A working directory reference number that encodes the volume and 
parent directory of the file. 

The file type. 

Reserved. 

The filename. 
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File Specification Routines 



If your appUcation has no special user interface requirements, you can use the 
StandardGetFile and StandardPutFile procedures to display the default dialog 
boxes for opening and saving documents. For a description of more advanced file 
specification routines, see the chapter "Standard File Package" in this book. 



StandardGetFile 



You can use the StandardGetFile procedure to display the default Open dialog box 
when the user is opening a fUe. 

PROCEDURE StandardGetFile (fileFilter: FileFilterProcPtr; 

numTypes: Integer; 

typeList: SFTypeList; 

VAR reply: StandardFileReply) ; 

fileFilter A pointer to an optional file fiher function, provided by your application, 
through which StandardGetFile passes files of the speafied types. 

nuniTypes The number of fUe types to be displayed. If you specify a numTypes 
value of -1, the first filtering passes files of all types. 

typeList A list of file types to be displayed. 

reply The reply record, which StandardGetFile fills in before returning. 



DESCRIPTION 

The StandardGetFile procedure presents a dialog box through which the user 
specifies the name and location of a file to be opened. While the dialog box is active, 
StandardGetFile gets and handles events until the user completes the mteraction, 
either by selecting a file to open or by canceling the operation. StandardGetFile 
returns the user's input in a record of type StandardFileReply. 
The fileFilter, numTypes, and typeList parameters together determine which 
files appear in the displayed list. The first filtering is by file type, which you specify m 
the numTypes and typeList parameters. The numTypes parameter specifies the 
number of file types to be displayed. You can specify one or more types. If you specify a 
numTypes value of -1, the first filtering passes files of all types. 

The fileFilter parameter points to an opfional file filter hmction, provided by your 
application, through which StandardGetFi le passes files of the specified types. See 
the chapter "Standard FUe Package" in this book for a complete description of how you 
specify this filter function. 
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SPECIAL CONSIDERATIONS 

The StandardGetFile procedure is not available in all versions of system software. 
Use the Gestalt fimction to determine whether StandardGetFile is available before 
calling it. 

Because S t andardGetFi le may move memory, you should not call it at interrupt time. 



StandardPutFile 



You can use the StandardPutFile procedure to display the default Save dialog box 
when the user is saving a file. 

PROCEDURE StandardPutFile (prompt: Str255; def aultNaine : Str255; 

VAR reply: StandardFileReply) ; 

prompt The prompt message to be displayed over the text field. 

defaultName 

The initial name of the file, 
reply The reply record, which St andardPutFi le fills in before returning. 

DESCRIPTION 

The StandardPutFile procedure presents a dialog box through which the user 
specifies the name and location of a file to be written to. The dialog box is centered on 
the screen. While the dialog box is active, StandardPutFile gets and handles events 
until the user completes the interaction, either by selecting a name and authorizing the 
save or by canceling the save. The StandardPutFile procedure retvmns the user's 
input in a record of type StandardFileReply. 

SPECIAL CONSIDERATIONS 

The StandardPutFile procedure is not available in all versions of system software. 
Use the Gestalt function to determine whether StandardPutFile is available before 
calling it. 

Because StandardPutFile may move memory, you should not call it at interrupt time. 

File Access Routines 

This section describes the File Manager's file access routines. When you call one of these 
routines, you specify a file by a path reference nvimber (which the File Manager returns 
to yoiur application when your application opens the file). Unless your application has 
very specialized needs, you should be able to manage all file access (for example, writing 
data to the file) using the routines described in this section. Typically you use these 
routines to operate on a file's data fork, but in certain circumstances you might want to 
use them on a file's resource fork as well. 
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Reading, W riting, and Closing Files 

You can use the functions FSRead, FSWr it e, and FSClose to read data from a file, 
write data to a file, and close an open file. AU three of these fiinctions operate on open 
files. You can use any one of a variety of routines to open a file (for example, 
FSpOpenDF). 



FSRead 



You can use the FSRead function to read any number of bytes from an open file. 

FUNCTION FSRead (refNum: Integer; VAR count: Longint ; 
buffPtr: Ptr) : OSErr; 

refNum The file reference number of an open file. 

count On input, the number of bytes to read; on output, the number of bytes 

actually read. 

buf f Pt r A pointer to the data buffer into which the bytes are to be read. 



DESCRIPTION 

The FSRead hmction attempts to read the requested number of bytes from the specified 
file into the specified buffer. The buf f Ptr parameter points to that buffer; this buffer is 
allocated by your application and must be at least as large as the count parameter. 
Because the read operation begins at the current mark, you might want to set the mark 
first by calling the SetFPos function. If you try to read past the logical end-of-file, 
FSRead reads in all the data up to the end-of-file, moves the mark to the end-of-file, and 
rehuns eof Err as its function result. Otherwise, FSRead moves the file mark to the byte 
following the last byte read and returns noEr r. 



RESULT CODES 



noErr 


0 


ioErr 


-36 


fnOpnErr 


-38 


eofErr 


-39 


posErr 


^0 


f LckdErr 


^5 


paramErr 


-50 


rfNumErr 


-51 


afpAccessDenied 


-5000 



No error 

I/O error 

File not open 

Logical end-of-file reached 

Attempt to position mark before start of file 

File is locked 

Negative count 

Bad reference number 

User does not have the correct access to the file 
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FSWrite 



You can use the FSWrite function to write any number of bytes to an open file. 



DESCRIPTION 



The FSWr i te function takes the specified number of bytes from the specified data buffer 
and attempts to write them to the specified file. Because the write operation begins at the 
current mark, you might want to set the mark first by calling the SetFPos fimction. 

If the write operation completes successfully, FSWrite moves the file mark to the 
byte following the last byte written and returns noEr r. If you try to write past the 
logical end-of-file, FSWrite moves the logical end-of-file. If you try to write past 
the physical end-of-file, FSWrite adds one or more clumps to the file and moves the 
physical end-of-file accordingly. 



I 



o 

Q- 



FUNCTION FSWrite (refNum: Integer; VAR count: Longint; ^ 
buffPtr: Ptr): OSErr; g 



o 
31 



refNum The file reference number of an open file. 

count On input, the nim\ber of bytes to write to the file; on output, the number ^ 

of bytes actually written. g 
buf f Ft r A pointer to the data buffer from which the bytes are to be written. 



ta 

CD 

3 

CD 
3 



RESULT CODES 



noErr 


0 


dskFulErr 


-34 


ioErr 


-36 


fnOpnErr 


-38 


posErr 


^0 


wPrErr 




fLckdErr 


-45 


vLckdErr 


-46 


paramErr 


-50 


rfNumErr 


-51 


wrPermErr 


-^1 



FSClose 



No error 
Disk hill 
I/O error 
File not open 

Attempt to position mark before start of file 

Hardware voliime lock 

File is locked 

Software volume lock 

Negative count 

Bad reference number 

Read/ write permission doesn't allow writing 



You can use the FSClose function to dose an open file. 
FUNCTION FSClose (refNum: Integer): OSErr; 
refNum The file reference number of an open file. 
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DESCRimON 



The FSClose hmction removes the access path for the specified ffle and writes the 
contents of the volume buffer to the volume. 

Note 

The FSClose function calls PBFlushFile intemaUy to wnte the file s 
bytes onto the volume. To ensure that the file's catalog entry is updated, 
you should call FlushVol after you call FSClose. ♦ . 



▲ WARNING 

Make sure that you do not call FSClose with a file reference number 
of a file that has already been closed. Attempting to close the same file 
twice may result in loss of data on a volume. See the description of 
file control blocks in the chapter "File Manager" in this book for a 
discussion of how this can happen. A 



RESULT CODES 



noErr 

ioErr 

fnOpnErr 

fnfErr 

rfNumErr 



0 No error 

-36 I/O error 

-38 File not open 

-43 File not foimd 

-51 Bad reference number 



Marxipulating the FUe Mark 



You can use the hmctions GetFPos and SetFPos to get or set the current position of the 
file mark. 



GetFPos 



You can use the GetFPos function to determine the current position of tixe mark before 
reading from or writing to an open file. 

FUNCTION QetFPos (refNum: Integer; VAR filePos: Longint) : OSErr; 

re f Num The file reference ntunber of an open file, 
f i 1 ePo s On output, the current position of the mark. 



DESCRIPTION 

The GetFPos function returns, in the f ilePos parameter, the current position . 
mark for \he specified open file. The position value is zero-based; ti^at is, the val 
f ilePos is 0 if the file mark is positioned at the beginning of the file. 
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RESULT CODES 

noErr 

ioErr 

fnOpnErr 

rfNumErr 

gfpErr 



u INO error 

-36 I/O error 

-38 File not open 

-51 Bad reference number 

-52 Error during GetFPos 



SetFPos 



You can use the SetFPos function to set the position of the file mark before reading 
from or writing to an open file. 

FUNCTION SetFPos (refNum: Integer; posMode: Integer; 

posOff: Longint) : OSErr; 

r e f Num The file reference number of an open file. 
posMode The positioning mode. 
posOf f The positioning offset. 



DESCRIPTION 



The SetFPos function sets the file mark of the specified file. The posMode parameter 
indicates how to position the mark; it must contain one of the following values: 



CONST 

fsAtMark 
f sFromStart 
f sFromLEOF 
f sFromMark 



0; {at current mark} 

1; (set mark relative to beginning of file} 

2; {set mark relative to logical end-of-file} 

3; {set mark relative to current mark} 



If you specify fsAtMark, the mark is left wherever it's currently positioned, and the 
posOf f parameter is ignored. The next three constants let you position the mark relative 
to either the beginning of tfie file, the logical end-of-file, or the current mark. If you 
specify one df Ihese three constants, you must also pass in posOf f a byte offset (either 
positive or negative) from the specifie4 point. If you specify f sFromLEQF, the value in 
posOf f must be less than or equal to 0.. 



RESULT COPES 



noErr 

ioErr 

friOpnErr 

epfErr 

posErr 

rfNiomErr 



0 No error 

-36 I/O error 

-38 File not open 

-39 Logical end-of-file reached 

-40 Attempt to position mark before start of file 

-51 Bad reference number 
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Manipulating the End-of-File 



You can use the functions GetEOF and Set^OF to get or set the logical end-of-file of an 
dpen file. 



GetEOF 



You can use the GetEOF function to detennine the current logical end-of-file of an open 
file. 

FUNCTION GetEOF (refNum: Integer; VAR logEOF: Longint) : OSErr; 

r e f Num The file reference number of an open file. 
logEOF On output, the logical end-of-file. 



DESCRIPTION 



The GetEOF function returns, in the logEOF parameter, the logical end-of-file of the 
specified file. 



RESULT CODES 



noErr 


0 


ioErr 


-36 


fnOpnErr 


-38 


rfNumErr 


-51 


afpAccessDenied 


-5000 



SEE ALSO 



For a description of the logical and physical end-of-file, see the section "File Access 
Characteristics" on page 1-8. 



SetEOF 



You can use the SetEOF hincfion to set the logical end-of-file of an open file. 

FUNCTION SetEOF (refNum: Integer; logEOF: Longint): OSErr; 

re f Num The. file reference number of an open file. 
logEOF The logical end-of-file. 
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DESCRIPTION 



The Set: EOF function sets the logical end-of-file of the specified file. If you attempt to set 
the logical end-of-file beyond the physical end-of-file, the physical end-of-file is set 1 
byte beyond the end of the next free allocation block; if there isn't enough space on the 
volume, no change is made, and SetEOF returns dskFulErr as its function result. 

If you set the logEOF parameter to 0, all space occupied by the file on the volume is 
released. The file still exists, but it contains 0 bytes. Setting a file fork's end-of-file to 0 is 
therefore not the same as deleting the file (w^hich removes both file forks at once). 



RESULT CODES 



noErr 


0 


No error 


dskFulErr 


-34 


Disk full 


ioErr 


-36 


I/O error 


fnOpnErr 


-38 


File not open 


wPrErr 


-44 


Hardware volume lock 


fLckdErr 


-45 


File is locked 


vLckdErr 


-46 


Softv^are volume lock 


rfNumErr 


-51 


Bad reference number 


wrPermErr 


-61 


Read/v^rite permission doesn't allow writing 



I 



o 

CL 

c 
o 

3 

o 
© 

to 

(Q 
CD 

3 
a> 

3 



SEE ALSO 



For a description of the logical and physical end-of-file, see the section "File Access 
Characteristics" on page 1-8. 



File and Directory Marupulation Routines 

The File Manager includes a set of file and directory manipulation routines that accept 
FSSpec records as parameters. Depending on the requirements of your application and 
on the environment in which it is running, you may be able to accomplish all your file 
and directory operations by using these routines. 

Before calling any of these routines, however, you should call the Gestalt fimction to 
ensiure that they are available in the operating environment. (See 'Testing for File 
Management Routines" on page l-14for an illustration of calling Gestalt.) If these 
routines are not available, you can call tihe corresponding HFS routines. 

Opening, Creating, and Deleting Files 

The File Manager provides the FSpOpenDF, FSpCreate, and FSpDelete routiunes, 
vi^hich allow you to open, create, and delete files. 
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FSpOpenDF 



You can use the FSpOpenDF function to open a file's data fork. 

FUNCTION FSpOpenDF (spec: FSSpec; permission: SignedByte; 

VAR refNum: Integer) : OSErr; 

spec An FSSpec record specifying the file whose data fork is to be opened. 

permission 

A constant indicating the desired file access permissions, 
r e f Num A reference number of an access path to the file's data fork. 



DESCRIPTION 



The FSpOpenDF function opens the data fork of the file specified by the spec parameter 
and returns a file reference number in the refNum parameter. You can pass that reference 
number as a parameter to any of the low- or high-level file access routines. 

The permission parameter specifies the kind of access permission mode you want. You 
can specify one of these cor\stants: 



CONST 

fsCurPerm = 0 

f sRdPerm = 1 

fsWrPerm = 2 

f sRdWrPerm = 3 

f sRdWrShPerm = 4 



{whatever permission is allowed} 

{read permission} 

{write permission} 

{exclusive read/write permission} 

{shared read/write permission} 



In most cases, you can simply set the permission parameter to f sCurPerm. Some 
applications request f sRdWrPerm, to ensure that they can both read from and write to a 
fUe. 



RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


tmfoErr 


-42 


Too many files open 


fnfErr 


^3 


File not found 


opWrErr 


-49 


File already open for writing 


permErr 


-54 


Attempt to open locked file for writing 


dirNFErr 


-120 


Directory not found or incomplete pathname 


a f pAcces s Denied 


-5000 


liser does not have the correct access to the file 
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FSpCreate 



You can use the FSpCreate function to create a new file. 

FUNCTION FSpCreate (spec: FSSpec; creator: OSType; 

fi'leType: OSType; scriptTag: ScriptCode) : 
OSErr ; 

spec An FSSpec record specifying the file to be created, 

creator The creator of the new file, 
f i 1 eTy pe The file type of the new file. 

scriptTag The code of the script system in which the filenanie is to be displayed. If 
you have established the name and location of the new file using either 
the StandardPutFile or CustomPutFile procedure, specify the script 
code returned in the reply record. (See the chapter "Standard File 
Package" in this book for a description of StandardPutFile and 
CustomPu tFi le.) Otherwise, specify the system script by setting the 
scriptTag parameter to the value smSystemScript. 



DESCRIPTION 

The FSpCreate function creates a new file (both forks) with the specified type, creator, 
and script code. The new file is unlocked and empty. The date and time of creation and 
last modification are set to the current date and time. 

See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for 
information on file types and creators. 

Files created using FSpCreate are not automatically opened- If you want to write 
data to the new file, you must first open the file using a file access routine (such 
as FSpOpenDF). 

Note 

The resource fork of the new file exists but is empty. You'll need to call 
one of the Resource Manager procedures CreateResFile, 
HCreateResFile, or FSpCreateResPile to create a resource map in 
the file before you can Open it (by calling one of the Resource Manager 
ftmctions OpenResFile, HOpenResFile, or FSpOpei^ResFile). ♦ 
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RESULT CODES 



noErr 


0 


No error 


ulLr Ulc*i IT 


—oo 


me Qireciury ruii 


dskFulErr 


-34 


Disk is full 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 




Directory not found or incomplete pathname 


wPrErr 


■ -44 


Hcirdware volume lock 


vLckdErr 


-46 


Software volume lock 


dupFNErr 


-48 


Ehiplicate filename and version 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access 


af pOb 3 ectTypeErr 


-5025 


A directory exists with that name 



FSpDelete 



You can use the FSpDelete function to delete files and directories. 

FUNCTION FSpDelete (spec: FSSpec) : OSErr; 

spec An FSSpec record specifying the file or directory to delete. 

DESCRIPTION 

The FSpDelete function removes a file or directory. If the specified target is a file, both 
forks of the file are deleted. The file ID reference, if any; is removed. 

A file must be closed before you can delete it Similarly, a directory must be empty before 
you can delete it. If you attempt to delete an open file or a nonempty directory, 
FSpDelete returns the result code f BsyErr. FSpDelete also returns the result code 
f BsyErr if the directory has an open working directory associated with it. 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


-43 


File not found 


wPrErr 


-44 


Hardware volume lock 


fLckdErr 


-45 


File is locked 


vLckdErr 


-46 


Software volume lock 


fBsyErr 


-47 


File busy, directory not empty, or working directory 
control block open 


dirNFErr 


-120 


Directory not found or incomplete pathnarne 


a f pAccessDenied 


-5000 


User does not have the correct access 
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Exchanging the Data in Two Files 



The function FSpExchangeFiles aUows you to exchange the data in two files. 



FSpExchangeFiles 



You can use the FSpExchangeFiles function to exchange the data stored in two files 
on the same voliune. 

FUNCTION FSpExchangeFiles (source: FSSpec; dest: FSSpec) : OSErr; 

The source file. The contents of this file and its file information are placed 
in the Hie specified by the dest parameter. 

The destination file. The contents of this file and its file information are 
placed in the fOe specified by the source parameter. 



source 



dest 



DESCRIPTION 



The FSpExchangeFi les hmction swaps the data in two fUes by changing \he 
information in the volume's catalog and, if the files are open, in the file control blocks^- • 
You should use FSpExchangeFiles when updating an existing file, so that the file ID 
remains valid in case the fUe is being tracked through its file ID. The FSpExchangeFiles 
hmction changes the fields in the catalog entries that record the location of the data and 

the modification dates. It swaps both tiie data forks and the resource forks. 

The FSpExchangeFiles hmction works on both open and closed files. If either file is 

open, FSpExchangeFiles updates any file control blocks associated with the fUe. 

Exchanging the contents of two files requires essentially the same access permissions as 

opening both files for writing. 

The files whose data is to be exchanged must both reside on the same volume. If they do 
not, FSpExchangeFiles rehims the result code dif f VolErr. 



RESULT CODES 

noErr 0 No error 

nsvErr -35 Volxune not found 

ioErr -36 I/O error 

fnfErr -43 File not foimd 

fLckdErr ^5 File is locked 

vLckdErr ^6 Volimie is locked or read-only 

paramEr r -50 Function not supported by volume 

volOfflinErr -53 Volume is offline 

wrgVolTypErr -123 Not an HFS volume 

di f f VolErr -1303 Files on different volumes 

af pAccessDenied -5000 User does not have the correct access 

af pOb j ectTypeErr -5025 Object is a directory, not a file 

af pSameOb j ect Err -5038 Source and destination files are the same 
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Creating File System Specifications 



The FSMakeFSSpec function allows you to create FSSpec records. 



FSMakeFSSpec 



You can use the FSMakeFSSpec function to initialize an FSSpec record to particular 
values for a file or directory. 

FUNCTION FSMakeFSSpec (vRefNum: Integer; dirlD: Longint; 

fileN^me: Str255; VAR spec: FSSpec): 
OSErr; 



vRef Num 



dirlD 



f ileName 



spec 



A volume specification. This parameter can contain a volume reference 
number, a working directory reference number, a drive number, or 0 (to 
specify the default volume). 

A directory specification. This parameter usually specifies the parent 
directory ID of the target object. If the directory is sufficiently specified by 
either the vRef Num or f ileName parameter, dirlD can be set to 0. If yoii 
explicitly specify dirlD (that is, if it has any value other than 0), and -if 
vRefNum specifies a working directory reference number, dirlD 
overrides the directory ID included in vRef Num. If the f i leName 
parameter contains an empty string, FSMakeFSSpec creates an FSSpec 
record for a directory specified by either the di r ID or vRe f Num 
parameter 

A full or partial pathname. If f ileName specifies a full pathname, 
FSMakeFSSpec ignores both the vRef Num and dirlD parameters. A 
partial pathname might identify only the final target, or it might include 
one or more parent directory ncimes. If f ileName sp>ecifies a partial 
pathname, then vRef Num, dirlD, or both must be valid. 

A file system specification to be filled in by FSMakeFSSpec. 



DESCRIFnON 

The FSMakeFSSpec function fills in the fields of the spec parameter vising the 
information contained in the other three pcurameters. Call FSMakeFSSpec whenever 
you want to create an FSSpec record. 

You can pass the input to FSMakeFSSpec in several ways. The chapter "File 
Manager" in this book explains how FSMakeFSSpec interprets its input. 

If the specified volume is movmted and the specified parent directory exists, but the 
target file or directory doesn't exist in that location, FSMakeFSSpec fills in the record 
and then returns f nf Err instead of noErr. The record is valid, but it describes a target 
that doesn't exist. You can use the record for other operations, such as creating a file with 
the FSpCreate function. 

c 
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In addition to the result codes that foUow, FSMakeFSSpec can return a number of other 
File Manager error codes. If youx application receives any result code other than noErr 
or f nf Err, all fields of the resulting FSSpec record are set to 0. 



RESULT CODES 



noErr 
nsvErr 
• fnf Err 



0 No error 
-35 Volume doesn't exist 

-43 File or directory does not exist (FSSpec is still valid) 



Volume Access Routines 



This section describes the high-level volume access routines. Unless your application has 
very specialized needs, you should be able to manage all volume access usmg the 
routines described in this section. In fact, most appUcations are likely to need only the 
FlushVol function described in the next section, "Updating Volumes." 
When you caU one of these routines, you specify a volume by a volume reference 
number (which you can obtain, for example, by caUing the GetVInf o function, or from 
the reply record returned by the Standard File Package). You can also specify a volume 
by name, but this is generally discouraged, because there is no guarantee that volume 
names are imique. 



Updating Volumes 



When you close a fUe, you should call FlushVol to ensure that any changed contents of 
the file are written to the volume. 



FlushVol 



You can use the FlushVol function to write the contents of the volume buffer and 
update information about the volume. 

FUNCTION FlushVol (volName: StringPtr; vRefNum: Integer) : OSErr; 
volName A pointer to the niame of a mounted volume. 

vRef Num A volume reference number, a working directory reference number, a 
drive number, or 6 for the default volume. 



DESCRIPTION 



0.1 the specified volume, the FlushVol hmction writes the contents of the assoaated 
volume buffer and descriptive information about the volume (if they've changed smce 
the last time FlushVol was called). This information is written to the volume. 
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RESULT CODES 



noErr 

nsvErr 

ioErr 

bdNamErr 

paramErr 

nsDrvErr 



0 No error 

-35 No such volume 

-36 I/O error 

-37 Bad volume r\ame 

-50 No default volume 

-56 No such drive 



Obtaining Volume Information 



You can get information about a voltune by calling the GetVInf o or GetVRef Num 
function. 



GetVInfo 



You can use the GetVInfo function to get information about a mounted volume. 

FUNCTION GetVInfo (drvNum: Integer; volName: StringPtr; 

VAR vRefNum: Integer; 

VAR freeBytes: Longint) : OSErr; 

drvNum The drive number of the volume for which information is requested, 

vol Name On output, a pointer to the name of the specified volume. 

vRef Num The voltune reference number of the specified volume. 

freeBytes The available space (in bytes) on the specified volume. 



DESCRIPTION 



The GetVInfo function returns the name, volume reference number, and available 
space (in bytes) for the specified volume. You specify a volume by providing its drive 
number in the drvNum parameter. You can pass 0 in the drvNum parameter to get 
information about the default volume. 



RESULT CODES 



noErr 0 No error 

nsvErr -35 No such voliune 

paramErr -50 No default volume 
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GetVRefNum 



I 



You can use the GetVRefNum function to get a volume reference number from a file 
reference number. o 

c 
o 

FUNCTION GetVRefNum (refNum: Integer; VAR vRefNum: Integer): o 

OSErr; o 

r e f Num The file reference number of an open file. ^ 

(U 



vRe f Num On exit, the volume reference number of the volume contaiiung the file 

. specified by refNum. ^ 



(D 
3 



DESCRIPTION 



The GetVRefNum function rettims the volume reference number of the volume 
containing the specified file. If you also v^ant to determine the directory ID of the 
specified file's parent directory, call the PBGetFCBInf o function. 



RESULT CODES 

noErr 0 No error 

r f NumEr r -51 Bad reference number 



Application Launch File Routines 



You can call Get AppParms to determine your application's name and the reference 
number of its resource file. When your application starts up, you can call 
Count AppFiles to determine whether the user selected any documents to open or 
print. If so, you can call GetAppFiles and ClrAppFiles to process the information 
passed to your application by the Finder. 

Note 

If your application supports high-level events, you receive this 
iitf ormatibn from the Finder in an Open Documents or Print 
Oocuments event. ♦ 
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You can use the GetApp Farms procedure to get information about the current 
application and about jSles selected by the user for opening or printing. 

PROCEDURE GetAppParms (VAR apName: Str255; VAR apRefNum: Integer; 

VAR apParam: Handle) ; 

apName On output, the name of the calling application. 

apRefNum On output, the reference number of the application's resource file. 

apParam On output, a handle to the Finder information about files to open or print. 



DESCRIPTION 

The GetAppParms procedure returns information about the current application. You can 
call GetAppParms at application launch time to determine which files, if any, the user 
has selected in the Finder for opening or. printing. You can call GetAppParms at any 
time to determine the current application's name and the reference number of the 
application's resource fork. 

The GetAppParms procedure returns the application's name in the apName parameter 
and the reference number of its resource fork in the apRefNum parameter. A handle to 
the Finder information is returned in apParam. This information consists of a woird that 
encodes the message or action to be performed, a word that indicates how many files to 
process, and a list of Finder information about each such file. The Finder information has 
the structure of an AppFi le record, except that the filename occupies only as many 
bytes as are reqtdred to hold the name (padded to an even number of bytes, if 
necessary). h\ general, it is easier to use the GetAppFiles procedure to access the 
Finder information. 



SPECIAL CONSIDERATIONS 

If you simply want to determine the application's resource file reference number, you 
can call the Resource Manager function CurResFi le when your application starts up. 

If you need more extensive information about the application than GetAppParms 
provides, you can use the Process Manager function GetCur rent Process. 



ASSEMBLY-UVNGUAGE INFORMATION 

You can get the application's name, reference number, and handle to the Finder 
information directly from the global variables Cur ApName, CurApRef Num, and 
AppParmHandle. 
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CountAppFiles 



DESCRIPTION 



I 



You can use the CountAppFiles procedure to determine how many documents (if any) | 
the user has selected at application launch time for opening or pnntmg. | 



PROCEDURE CountAppFiles (VAR message: Integer; ^ 

VAR count: Integer); ^ 

message The action to be performed on the selected files. | 
count The number of files selected. w 

(D 

3 

(D 

The CountAppFiles procedure deciphers the Finder information passed to your 
appUcation and returns information about the files that were selected when your 
appUcadon was started up. On exit, the count parameter contains the number of 
selected files, and the message parameter contains an integer that indicates whether the 
files are to be opened or printed. The message parameter contams one of these 
constants: 

CONST 

appOpen = 0; {open the document (s) ) 
appPrint = 1; {print the document (s) } 



G etAppFiles . 

You can use the Get AppFi les procedure to retrieve information about each file selected 
at application startup for opening or printing. 

PROCEDURE GetAppFiles (index: Integer; VAR theFile: AppFile) ; 

index The index of ttie file whose information is retumed. 

theFile A structure CQntairmig*he returned informatiorv. 



DESCRIPTION 



The GetAppFiles procedure returns information about a file that was selected when 
your application was started up (as listed in the Finder information). The index 
parameter indicates the file for which information should be rehimed; it must be 
between 1 and the number retamed by CountAppFiles, inclusive. 
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C lrAppFiles 

You can use the ClrAppFiles procedure to notify the Finder that you have processed 
the information about a file selected for opening or printing at application startup. 

PROCEDURE ClrAppFiles (index: Integer); 

index The index of the file whose information is to be cleared. 



DESCRIPTION 

The ClrAppFiles procedure changes the Finder information passed to your 
application about the specified file so that the Finder knows you've processed the file. 
The index parameter must be between 1 and the number returned by Count AppFiles, 
inclusive. You should call ClrAppFiles for every document your application opeits or 
prints, so that the information returned by CountAppFiles and GetAppFiles is 
always correct The ClrAppFiles procedure sets the file type in the Finder information 
to 0- 
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Sunmiary of File Management 



I 



Pascal Summary 



Constants 



o 

Q. 
C 

o 
o* 

3 



0) 
3 

(Q 
0) 

3 

(D 
3 



CONST 

(Gestalt constants) 

gestaltFSAttr 

gestaltHasFSSpecCalls 

gestaltStandardFileAttr = 

gestaltStandardFile58 

gestaltFindFolderAttr 

gestaltFindFolderPresent= 



' f s * ; 
1 ; 

'stdf ' ; 
0; 

•fold' 

0; 



{file system attributes selector) 
{supports FSSpec records) 
{Standard File attributes selector) 
{supports StandardPutFile etc.) 
{FindFolder attributes selector) 
{FindFolder is present) 



{access modes for opening files) 

_ Q. {whatever permission is allowed) 

_ {read permission) 

_ 2; {write permission) 

= 3; {exclusive read/write permission) 

= 4; {shared read/write permission) 



f sCurPerm 
f sRdPerm 
f sWrPera 
f sRdWrPerm 
f sRdWrShPerm 



{file mark positioning modes) 



fsAtMark 
f sFromStart 
f sFromLEOF 
f sFromMark 
rdVerify 



0; 
1; 
2i 
3; 
64; 



{at current mark) 

{set mark relative to beginning of file) 
{set mark relative to logical end-of-file) 
{set mark relative to current mark) 
{add to above for read-verify) 



{messages from CountAppFiles) 

appOpen - 0; {open the document (s) ) 

appPrint = 1; ^P^^^^ the document (s)) 
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Data Types 



File System Specification Record 



TYPE FSSpec 
RECORD 
. vRefNum: 
parlD: 
name: 
END; 



Integer; 
Longint ; 
Str63; 



{volume reference number} 
(directory ID of parent directory} 
{filename or directory name} 



FSSpecPtr 
FSSpecHandle 



^FSSpec; 
^FSSpec Ptr; 



Standard File Reply Record 



TYPE StandardFileRepIy= 



RECORD 

sfGood: 

sf Replacing: 

sfType: 

sf File: 

sf Script : 

sf Flags: 

sf IsFolder : 

sflsVolume: 

sfReservedl : 

sfReserved2 : 

END; 



Boolean; 

Boolean; 

OSType; 

FSSpec ; 

ScriptCode; 

Intieger; 

Boolean; 

Boolean; 

Longint ; 

Integer; 



{TRUE if user did not cancel} 

{TRUE if replacing file with same name} 

{file type} 

{selected item} 

{script of selected item's name} 
{Finder flags of selected item} 
{selected item is a folder} 
{selected item is a volume} 
{reserved} 
{reserved} 



Application Files Record 

TYPE AppFile 
RECORD 

vRefNum: 
fType: 
versNum: 
fName: 
END; 



Integer; {worlcing directory reference number} 

OSType; {file type} 

Integer; {version niunber; ignored} 

Str255; {filename} 



SFTypeList 



= ARRAYt0..31 OF OSType; 



FileFilterProcPtr = ProcPtr; {file filter function} 
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Fil e Specification Routines ^ . 

Opening Files 

PROCEDURE StandardGetFile (fileFilter: FileFilterProcPtr ; 

numTypes: Integer; typeList: SFTypeList; 
VAR reply: StandardFileReply) ; 

Saving Files 

PROCEDURE StandardPutFile 

File Access Routines 

Reading, Writing, and Closing Files 

FUNCTION FSRead 

FUNCTION FSWrite 
FUNCTION FSClose 

Manipulating the File Mark 

FUNCTION GetFPos 
FUNCTION SetFPos 

Manipulating the End-of-File 

FUNCTION GetEOF 
FXJNCTION SetEOF 

Fil e and Directory Manipulation Routines ^ 

Opening, Creating, and Deleting Files 

FUNCTION FSpOpenDF (spec: FSSpec; permission: SignedByte; 

VAR refNiim: Integer): OSErr; 

FUNCTION FSpCreate (spec: FSSpec; creator: OSType; 

fileType: OSType; scriptTag: ScriptCode) : 
OSErr; 

FUNCTION FSpDelete (spec: FSSpec): OSErr; 

Summary of Rle Management 



(prompt: Str255; defaultName: Str255; 
-VAR reply: StandardFileReply); 



(refNum: Integer; VAR count: Longint; 
buffPtr: Ptr) : OSErr; 
(refNum: Integer; V^R count: Longint; 
buffPtr: Ptr) : OSErr; 
(refNiim: Integer): OSErr; 

(refNum: Integer; VAR filePos: Longint): OSErr; 
(refNum: Integer; posMode: Integer; 
posOff: Longint): OSErr; 

(refNum: Integer; VAR logEOF: Longint) : OSErr; 
(refNum: Integer; logEOF: Longint): OSErr; 
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Exchanging the Data in Two Files 

FUNCTION FSpExchangeFiles (source: FSSpec; dest: FSSpec) : OSErr; 
Creating File System Specifications 

FUNCTION FSMakeFSSpec (vRefNum: Integer; dirlD: Longint; 

fileName: Str255; VAR spec: FSSpec) : OSErr; 

Volume Access Routines 



Updating Volumes 

FUNCTION FlushVol 



(volName: StringPtr; vRefNum: Integer): OSErr; 



Obtaining Volume Information 

FUNCTION GetVInfo 



FUNCTION iSetVRefNum 



(drvNum: Integer; volName: StringPtr; 
VAR vRefNum: Integer; VAR freeBytes: LongInt) : 
OSErr; 

(refNum: Integer; VAR vRefNum: Integer) OSErr ; 



Application Launch File Routines 



PROCEDURE GetAppParms 

PROCEDURE Count AppFiles 
PROCEDURE GetAppFiles 
PROCEDURE ClrAppFiles 



(VAR apName: Str255; VAR apRefNum: Integer; 
VAR apParam: Handle) ; 

(VAR message: Integer; VAR count: Integer); 
(index: Integer; VAR theFile: AppFile) ; 
(index: Integer); 



C Summary 



Constants 



/*Gestalt constants*/ 

#define gestaltFSAttr . • f s ' 

#deEine gestaltFullExtFSDispatching. 0 
#define gestaltHasFSSpecCalls 1 
#define gestaltFindFolderAttr 'fold' 
#define gestaltFindFolderPresent 0 



/*file system attributes selector*/ 
/♦exports HFSpispatch traps*/ 
/♦supports FSSpec records*/ 
/*FindFolder attributes selector*/ 
/*FindFolder is present*/ 
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/*Gestalt Standard File attributes selector and reply*/ 
ttdefine gestaltStandardFileAttr ' stdf ' 
ttdefine gestaltStandardFileSS 



0 



/^values for requesting file read/write permissions*/ 
enuih ( 

fsCurPerm = 0, 

.fsRdPerm =1, 

fsWrPerm = 2, 

fsRdWrPerm = 3, 

fsRdWrShPerm - = 4}; 



/*whatever permission is allowed*/ 
/*read permission*/ 
/*write permission*/ 
/♦exclusive read/write permission*/ 
/*shared read/write permission*/ 



/*file mark positioning modes*/ 
enum { 

fsAtMark = 0* 

fsFromStart = 1. 

fsFromLEOF = 2, 

fsFromMark = 3, 

rdVerify = ^4}; 

/♦messages from CountAppFiles* / 
eninn { 

appOperi = 0 , 

appPrint = l)? 



/*at current mark} 

/*set mark relative to beginning of file*/ 
/*set mark relative to logical end-of -f ile* / 
/*set mark relative to current mark*/ 
/*add to above for read- verify* / 



/ * open the document ( s ) * / 
/♦print the document (s) */ 



Data Types 



File System Specification Record 



struct FSSpec 
short 
long 
Str63 

}; 



vRefNum; 
par ID ; 
name ; 



/*file system specification*/ 
/♦volume reference number*/ 
/♦directory ID of parent directory*/ 
/♦filename or directory name*/ 



typedef struct FSSpec FSSpec; 
typedef FSSpec *FSSpecPtr; 
typedef FSSpecPtr *FSSpecHandler 



Summary of File Management ^'^^ 



TIVO-408446 



CHAPTER 1 



Introduction to Rle Management 



Standard File Reply Record 



struct StandardFileReply { 



/♦enhanced standard file reply record*/ 



Boolean sfGood; /*TRUE if user did not cancel*/ 

Boolean sf Replacing; / *TRUE if replacing file with same name*/ 

OSType sfType; /*file type*/ 

FSSpec sfFile; /*selected file, folder, or volume*/ 

ScriptCode sfScript; /*script of file, folder, or volume name*/ 

short sf Flags; /*Finder flags of selected item*/ 

Boolean sflsFolder; /*selected item is a folder*/ 

Boolean sflsVolume; /*selected item is a volume*/ 

long sfReservedl; /*reserved*/ 

short sfReserved2; /*reserved*/ 



}; 



typedef struct StandardFileReply StandardFileReply; 



Application Files Record 

struct AppFile { 
short 
OSType 
short 
Str255 
END; 



vRefNum; /*working directory reference number*/ 

fType; /*file type*/ 

versNum; /* vers ion number; ignored*/ 

fName; /*filename*/ 



typedef struct' AppFile AppFile; 

Standard File Type List 

typedef OSType SFTypeList [4 ] ; 

Callback Routine Pointer Types 

/*file filter function*/ 

typedef pascal Boolean ( *FileFilterProcPtr ) 

(ParmBlkPtr PB) , 

File Specification Routines 



Opening Files 

pascal void StandardGetFile (const Str255 prompt, 

FileFilterProcPtr fileFilter, 

short numTypes, SFTypeList typeList, 

StandardFileReply * reply ) ; 
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Saving Files 

pascal void StandardPutFile (const Str255 prompt, const Str255 defaultName. 

StandardFileReply *replY) ; 



File Access Routines 



Reading, Writing, and Closing Files 

pascal OSErr FSRead (short refNum, long *count, Ptr buf f Ptr) ; 

pascal OSErr FSWrite (short refNum, long *count, Ptr buf f Ptr) ; 

pascal OSErr FSClose (short refNum); 

Manipulating the File Mark 

pascal OSErr GetFPos (short refNum, long *f ilePos) ; 

pascal OSErr SetFPos (short refNum, short posMode, long posOff ) ; 

Manipulating the End-of-File 

pascal OSErr GetEOF - (short refNum, long *logEOF) ; 

pascal OSErr SetEOF (short refNum. long logEOF) ; 

File and Difectory Manipulation Routines 

Opening, Creating, and Deleting Files 

pascal OSErr FSpOpenDF (const FSSpec *spec, char permission, 

short * refNum) ; 

pascal OSErr FSpCreate (const FSSpec *spec, OSType creator 

OSType fileType, ScriptCode scriptTag) ; 

pascal OSErr FSpDelete (const FSSpec *spec) ; 



Exchanging the Data in Two Files 

pascal OSErr FSpExchangeFiles 



const FSSpec *source, const FSSpec *dest) 



Creating File System Specifications 

pascal OSErr FSMakeFSSpec (short vRefNum, long dirlD, 

ConstStr255Parain fileName, FSSpecPtr spec); 
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Volume Access Routines 
Updating Volumes 

pascal OSErr FlushVol {StringPtr volNalne, short vRefNum) 

Obtaining Volume Information 

pascal OSErr GetVXnfo . (short drvNum, StringPtr volName, 

short *vRefNum, long *freeBytes) ; 

pascal OSErr GetVRefNum (short refNum, short *vRefNum) ; 

Application Launch File Routines 



pascal void GetAppParms 

pascal void CountAppFiles 
pascal void GetAppFiles 
pascal void ClrAppFiles 



(Str255 apName, short *apRefNum, 
Handle *apParam) ; 

(short *message, short *count) ; 

(short index, AppFile *theFile) ; 

(short index) ; 



Assembly-Language Summary 



Global Variables 

AppParmHandl e long Handle to Finder information. 

Cur ApName 32 bytes Name of current application (length byte followed by up to 

31 characters). 

Cur ApRe f Nura word Reference number of current application's resource file. 
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Result Codes 

noErr 

dirFulErr 

dskFulErr 

nsvErr 

ioErr 

bdNamErr 

f nOpnErr 

eofErr 

posErr 

tmfoErr 

fnfErr 

wPrErr 

fLckdErr 

vLckdErr 

fBsyErr 

dupFNErr 

opWrErr 
paramErr 
rfNumErr 
gfpErr 

volOfflinErr 

pfermErr 

nsDrvErr 



wrPermErr 

dirNFErr 

wrgVolTypErr 

notAFileErr 

diffVolErr 

sameFileErr 

a fpAc cess Denied 

afpObjectTypeErr 

af pSameOb j ect Err 



0 
-33 
-34 
-35 
-36 
-37 
-38 
-39 
-40 
-42 
-43 
-44 
^5 
-46 
-Al 

-48 



No error 

File directory full 

All allocation blocks on the volume are full 
Volume not found 
I/O error 

Bad filename or volume name 
File not open 

Logical end-of-file reached 
Attempt to position mark before start of file 
Too many files open 
File not found 
Hardware volume lock 
File locked 

Software volume lock 

FUe is busy; one or more files are open; directory not 
empty or working directory control block is open 
A file with the specified name and version number 
already exists 
-49 File already open for writing 
-50 Parameter error 

-51 Reference number specifies nonexistent access path 
• -52 Error during GetFPos 

-53 Volume is offline 

-54 Attempt to open locked file for writing 

-56 Specified drive number doesn't match any number m 
the drive queue 

-61 Read / write permission doesn't allow writing 
-120 Directory not found or incomplete pathname 

-123 Not an HFS volume 
-1302 Specified file is a directory 
-1303 Files are on different volimies 
-1306 Source and destination files are the same 
-5000 User does not have the correct access to the file 
-5025 Object is a directory, not a file; a directory exists with 
that name 

-5038 Source and destination files are the same 



I 



o 

c 
o 



(O 
CD 

3 
o 

3 
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This chapter describes how your application can use the File Manager to store and access 
data in files or to manipulate files, directories, and volumes. It also provides a complete 
description of all File Manager routines, data types, and constants. 

You need to read the information in this chapter if you wish to use File Manager routines 
other than those described in the chapter "Introduction to File Management" earlier in 
this book. That chapter shows how to use the File Manager, the Standard File Package, 
and other system software components to handle the typical File menu commands and 
perform other common file-manipulation operations. This chapter addresses a nvunber 
of other important file-related issues, including 

■ using the low-level File Manager routines 

■ locking and xmlocking byte ranges in shared files 

■ searching a volume for files or directories satisfying certain criteria St 

u obtaining informiation about files, directories, and volumes 

This chapter also addresses some advanced topics of interest primarily to designers 
of very specialized applications or file-system utility programs. These advanced 
topics include 

■ how the File Manager orgaruzes file and directory data on disk 

■ how the File Manager organizes information in memory 

To use this chapter, you should already be familiar with the information presented in the 
chapter "Introduction to File Management" earlier in this book. 

This chapter begirds with a general introduction to the File Manager and the services it 
provides. Then it describes 

■ ways of identifying files, directories, and volumes 

■ file access permissions 

■ directory access privileges 

■ nmning in a shared environment 



I 



About the File Manager 

The File Maitiager is the part of ttie Madrttosh Operating System that manages the 
orgaiuzation, reading, and writing of data located on physical data storage devices 
such as disk drives. This data includes the data in docxmients as well as other 
collections of data used to maintain the hierarchical file system (HFS) and other system 
software services. To accomplish these tasks, the File Manager interacts vsnth many 
other components of the system software. For example, the Resoim:e Manager uses 
File Manager routines when it needs to read and write resource data. Similarly, the File 
Manager calls the Device Manager to perform the actual reading and writing of data 
on a physical data storage device. In general, you'll use the Resource Mariager to read 
and write data in a fQe's resource fork and the File Manager to read and write data in 
a file's data fork. You'll also use the File Manager to perform operations on directories 
and volimnes. 
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The File Manager provides a large number of routines for performing various operations 
on files, directories, and volumes. The requirements of your application will dictate 
which of these routines you will need to use. Many applicatioris simply need to open 
files, read and write the data in those files, and then close the files. Other applications 
might provide more capabilities, such as the ability to copy a file or move a file to 
another directory. A few file-system utilities perform even more extensive file operations 
and hence need to use some of the advanced routines provided by the File Manager For 
example, a disk scavenger might need to make a byte-by-byte search through a volume 
to find pieces of a deleted file. 

You can often use one of several File Manager routines to accomplish a particular task. 
This is because many of the File Manager routines are provided in two different forms: 
high level and low level. The low-level routines generally provide the greatest control 
over the requested task; they are identified by the prefixes PB and PBH, indicating that 
they take the address of a parameter block as a parameter. The high-level routines are 
always defined in terms of low-level routines; they are identified by prefixes such as FSp 
or H, indicating how you identify files or directories using those routines, or by no 
special prefix at all. 

You pass information to a high-level routine using the routine's parameters. A high-level 
routine has as many parameters as are necessary to pass the information it requires. 

You pass information to a low-level routine by filling in fields in a parameter block and 
then passing the address of the parameter block to the routine. In all cases, a low-level 
routine uses more fields in the parameter block than there are parameters in the 
corresponding high-level routine. As a result, you can use those low-level routines to 
perform more advanced operations or to provide more extensive information than you 
can with the corresponding high-level routines. This is the principal reason you might 
choose to use a low-level routine instead of its corresponding high-level routine. 

IMPORTANT 

If you use the low-level File Manager routines, be sure to clear all 
imused fields of the parameter block, a 

Low-level routines also accept a parameter indicating whether you want the routine to 
be executed synchronously or asynchronously. If you request synchronous execution, 
control does not return to your application until the routine has been executed. This 
allows you to inspect the routine's result code to see whether the routine was 
successfully completed. If so, your application can continue by performing other 
operations that depend on the successful completion of that routine. 

If you request asynchronous execution, an I/O request is put into the file I/O queue and 
control returns to your application immediately — ^possibly even before the actual I/O 
operation is completed. The File Manager takes requests from the queue one at a time 
and processes them; meanwhile, your application is free to work on other things. 
Routines that are executed asynchronously return control to your application with the 
result code noErr as soon as the call is placed in the file I/O queue. Return of control 
does not signal successful completion of the call, but simply successful queuing of the 
request. To determine when the call is actually completed, you can poll the ioResult 
field of the parameter block. This field is set to a positive number when the call is made 
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and set to the actual result code when the call is completed. If necessary, you can also 
install a completion routine that is executed when the asynchronous call is completed. 
See ''Completion Routines" on page 2-238 for details about completion routines. 

Note 

Although you can request asynchronous execution for most low-level 
routines, the device driver for the device on which the target file, 
directory, or volume resides might not support asynchronous 
operations. For example, the current implementation of the SCSI 
Manager allows synchronous execution only. The Sony disk driver and 
AppleShare server software do, however, support asynchronous 
operation. ♦ 

The following sections describe the various capabilities of the File Manager, For full 
details on any of the routines mentioned in these sections, see the descriptions given in 
"File Manager Reference" beginning on page 2-86. 



File Manipulation 

The File Manager provides a number of routines that allow you to manipulate files. You 
can open a file fork, read and write the data in it, adjust its logical end-of-file, set the file 
mark, allocate blocks to a file, and close a file. 

To manipulate the data in a file, you first need to open the file. You can open a file using 
one of several routines, depending on whether you want to use low-level or high-level 
routines and how you identify the file to open. Table 2-1 lists the file-opening routines. 



Table 2-1 Routines for opening file forks 



FSSpec 

FSpOpenDF 

FSpOpenRF 



HFS High-Level 

HOpenDF 
HOpenRF 
HOpen 



HFS Low-Level 

PBHOpenDF 
PBHOpenRF 
PBHOpen 



Description 

Open a file's data fork. 
Open a file's resource fork. 
Open a driver or file data fork. 



All the high-level FSSpec routines require you to specify a file using a file system 
specification record. All the HFS routines, whether high or low level, require you to 
specify a file by its volume, directory, and name. 

No matter which routine you use to open a file, you need to specify a file permission 
that governs the kind of access your application can have to that file. You can specify one 
of these constants: 



CONST 

f sCurPerm 
f sRdPerm 



= 0; {whatever permission is allowed} 
1; {read permission} 
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fsWrPerm = 2; {write permission} 

fsRdWrPerm = 3; {exclusive read/write permission} 

f sRdWrShPerm = 4; {shared read/write permission} 

Use the constant f sCurPerm to request whatever permission is currently allowed. If 
write access is unavailable (because the file is locked or because the file is already open 
with write access), then read permission is granted. Otherwise, read/ write permission 
is granted. 

Use the constant f sRdPerm to request permission to read the file. Sinnilarly, use the 
coi\stant f sWr Perm to request permission to write to the file. If write peimission is 
granted, no other access paths are granted write permission. Note, however, that the File 
Manager does not support write-only access to a file. As a result, f sWrPerm is 
synonymous with f sRdWrPerm. 

There are two types of read/write permission — exclusive and shared. Often you want 
exclusive read /write permission, so that users car\ safely read and alter portions of a file. 
If your application requests and is granted exclusive read/ write permission, no users are 
granted permission to write to the file; other users may, however, be granted permission 
to read the file. 

Shared read /write permission allows multiple access paths for writing and reading. It is 
safe to have multiple read/write paths open to a file only if there is some way of locking 
a portion of the file before writing to that portion of the file. You can use the File 
Manager functions PBLockRange and PBUnlockRange to lock and unlock ranges of 
bytes in a file. These functions, however, are supported only on remotely mounted 
volumes or on local volumes that are sharable on the network. As a result, you should 
request shared read/write permission only if range locking is available. See "Shared File 
Access Permissions" on page 2^15 for details on permissions in shared environments. 



Note 

Don't assume that successfully opening a file for writing ensures that 
you can actually write data to the file. The Rle Manager allows you to 
open with write permission a file located on a locked volume, and you 
won't receive an error until you first try to write data to the file. To be 
safe, yoii can call the PBHGetVInf o function to make sure that the 
voluihe is writable. ♦ 

When you successfully open a file fork^ yoii receive a file refcirence number that 
imiquely identifies the open file. You can pass that number to the File Manager routines 
that allow you to manipulate open files. Table 2-2 lists the routines that operate on 
open files. 

The File Manager provides a number of routines that allow you to operate on files that 
are closed. You can create, delete, get and set information, and lock and unlock files. 
You can also move files within a volume and exchange data in two files. Table 2-3 lists 
these routines. 
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Table 2-2 Routines for operating on open file forks 


High-Level 


Low-Level 


Description 


FSRead 


PBRead 


Read bytes from an open file fork. 


FSWrite 


PBWrite 


Write bytes to an open file fork. 


FSClose 


PBClose 


Close an open file fork. 


GetFPos 


PBGetFPos 


Get the position of the file mark. 


SetFPos 


PBSetFPos 


Set the position of the file mark. 


GetEOF 


PBGetEOF 


Get the current logical end-of-file. 


SetEOF 


PBSetEOF 


Set the current logical end-of-file. 


Allocate 


PBAllocate 


Add allocation blocks to a file fork. 


AllocContig 


PBAllocContig 


Add contiguous allocation blocks to a file fork. 




PBFlushFile 


Update the disk contents of a file fork. 


GetVRefNum 




Get volume reference number of an open file. 



Table 2-3 Floutlnes for operating on closed files 



FSSpec 

FSpCreate 



HFS High-Level 

HCreate 



FSpDelete HDelete 
FSpGetFInfo HGetFInfo 



FSpSetFInfo 
FSpSetFLock 
FSpRstFLock 
FSpCatMove 

FSpRename 



HSetFInfo 
HSetFLock 
HRstFLock 
CatMove 

HRencune 



HFS Low-Level 

PBHCreate 

PBHDelete 
PBHGetFInfo 

PBHSetFInfo 
PBHSetFLock 
PBHRstFLock 
PBCatMove 

PBHRename 
PBGetCatlnfo 

PBSetCatlnfo 



Description 

Create both forks of a 
new file. 

Delete both forks of a file. 

Get a file's Finder 
information. 

Set a file's Finder information. 

Lock a file. 

Unlock a file. 

Move a file or directory 
within a volume. 

Rename a file or directory. 

Get information about a file 
or directory 

Set information about a file 
or directory. 



Note 

You can use the fimctiorw listed in Table 2-3 on open files as well, except 
for those functions that create or delete file forks. ♦ 
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You can exchange the data in two files using the FSpExchangeFiles and 
PBExchangeFiles functions. If you need to create a file system specification record, 
you can use the FSMakeFSSpec or PBMakeFSSpec function. 

Directory Manipulation 

The File Manager provides a number of routines that allow you to manipulate 
directories. For example, you can create and delete directories, get information about a 
directory, and move and rename directories. The directory manipulation routines are 
listed in Table 2-4. 



Table 2-4 Routines for operating on directories 



FSSpec HPS High-Level 

FSpDirCreate DirCreate 

FSpDelete HDelete 

FSpGetFInfo HGetFInfo 

FSpSeCFInfo HSetFInfo 

FSpSetFLock HSetFLock 

FSpRstFLock HRstFLock 



FSpCatMove 



FSpRename 



CatMove 



HRename 



HPS Low-Level 

PBDirCreate 

PBHDelete 
PBHGetFInfo 

PBHSetFInfo 

PBHSetFLock 
PBHRstFLock 
PBCatMove 

PBHRename 
PBGetCatlnfo 

PBSetCatInf o 



Description 

Create a directory. 

Delete a directory 

Get Finder information for 
a directory. 

Set Finder information for 
a directory. 

Lock a directory. 

Unlock a directory. 

Move a file or directory within 
a volume. 

Rename a file or directory. 

Get information about a file 
or directory. 

Set information about a file 
or directory. 



The File Manager includes a number of routines that allow you to manipulate working 
directories. See Table 2t5. Most applications do not need to use working directories. 
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Table 2-5 Routines for manipulating working directories 



High-Level 

OpenWD 

CloseWD 
GetWDInfo 



Low-Levet 

PBOpenWD 

PBCloseWD 

PBGetWDInfo 



Description 

Open a working directory. 
Close a working directory. 
Get information about a working directory. 



Volume Manipulation 

The File Manager provides a number of routines that allow you to manipulate volumes. 
For example, you can obtain information about a mounted volume, update the 
information on a volume, urmiount a mounted volume or place it offline, and so forth. 
Most applications don't need explicit access to volumes. The Standard File Package and 
the Finder handle most events related to the insertion and ejection of disks. 

When the Event Manager function WaitNextEvent (or GetNextEvent) receives a 
disk-inserted event, it calls the Desk Manager fimction Sys temEvent. The Desk 
Manager in turn calls the File Manager function PBMountVol, which attempts to mount 
the volume on the disk. The result of the PBMountVol call is put into the high-order 
word of the event message, and the drive number is put into its low-order word. If the 
result code indicates that an error occurred, you need to call the Disk Initialization 
Manager routine DIBadMount to allow the user to initialize or eject the volume. For 
details, see the chapter "Disk Initialization Manager" in this book. 

After a volume has been mounted, your application can call GetVInf o, which returns 
the name, the amount of unused space, and the volume reference number. Given a file 
reference number, you can get the volume reference number of the volume containing 
that file by calling either GetVRef Num or GetiFCBInf o. 

You can unmount or place offline any volumes that aren't currently being used. To 
tmmount a volume, call UnmountVol, which flushes a volume (by calling FlushVol) 
and releases all of the memory it uses. To place a volimie offline, call PBOf f Line, which 
flushes a volume and releases all of the memory used for it except for the volume control 
block. The File Manager places offline volumes online as needed, but your application 
must remount any immounted volumes it wants to access. The File Manager itself may 
place volumes offline during its normal operation. 

Note 

If you make a call to an offline volume, the File Manager displays the 
disk switch dialog box and waits for the user to reinsert the disk 
containing the volume. When the user inserts the required disk, the File 
Manager moimts the volume and then reissues your original call. To 
avoid presenting the user with numerous disk switch dialog boxes, you 
might need to check that a volume is online before attempting to access 
data on it. ♦ 
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To protect against data loss due to power interruption or unexpected disk ejection, you 
should periodically call FlushVol (probably after each time you close a file), which 
writes the contents of the volume buffer and all access path buffers (if any) to the volume 
and updates the descriptive information contained on the volume. 

Whenever your application is finished with a disk, or when the user chooses Eject from a 
menu, call the E j ect function. This function calls FlushVol, places the volume offline, 
and then physically ejects the volume from its drive. 

If you would like all File Manager calls to apply to a particular volume, specify it as the 
default volume. You can use the HGetVol (or Get Vol) function to determine the name % 
and volume reference number of the default volume, and the Set Vol function to make J 
any mounted volume the default. 

Normally, volume initialization and naming are handled by the Disk Initialization 
Manager. If you want to initialize a volume explicitly or erase all files from a volume, 
you can call the Disk Initialization Manager directly When you want to change the name 
of a volume, call the HRename function. 

Table 2-6 summarizes the volume-manipulation routines. Most of these routines require 
you to specify a volume either by name or by volume reference number. 



Table 2-6 Routines for operating on volumes 



High-Level 


Low-Level 




PBMountVol 


Unmount Vol 


PBUnmountVol 


Eject 


.PBEject 




PBOffLine 


FlushVol 


PBFlushVol 


GetVol 


PBGetVol 


HGetVol 


PBHGetVol 


SetVol 


PBSetVol 


HSetVol 


PBHSetVol 


GetVInfo 


PBHGetVInfo 




PBSetVInfo 




PBHGetVolParms 




PBCatSearch 



Description 
Mount a volume. 

Unmount a volume. 

Eject a volume. 

Place a volume offline. 

Update a volume. 

Get the default volume. 

Get the default volume. 

Set the default volume. 

Set the default volume. 

Get information about a volume. 

Set information about a volume. 

Determine capabilities of a volume. 

Search a volume for files or directories 
satisfying certain criteria. 
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Volume Sear ching 

The File Manager provides several routines that you can use to search a volume for files 
or directories having specific characteristics. For example, you can search for all files 
with modification dates of two days ago or less or all directories with the string "Temp" 
in their names. 

In general, you should avoid searching entire volumes, because a search of large 
volumes can consume significant amovmts of time. Suppose you are looking for a 
particular file (for example, a dictionary file against which your application needs to 
check the spelling of a document). In this case, you can save time and increase the 
chances of finding the conect file by storing and later resolving an alias record that 
describes the desired file. See the chapter "Alias Manager" in this book for details on 
using alias records. 

Alternatively, suppose you need to find the location of a standard system directory, such 
as the Preferences folder or the Temporary Items folder. To perform this search most 
efficiently, you should use the FindFolder function. See the chapter "Finder Interface" 
in Inside Macintosh: Macintosh Toolbox Essentials for details. 

In some cases, however, you do need to search volumes. For instance, a backup utility 
needs to search an entire volume to find which files and directories, if any, might need to 
be backed up. In these cases, you can choose either of two general search strategies: you 
can search the volume's catalog by calling the PBCatSearch function, or you can use a 
recursive, indexed search by calling the PBGetCatInf o function (see Table 2-7). 

Table 2-7 Routines lor manipulating working directories 
Routine Description 

PBCat Search Search a volume's catalog file for files or directories. 

PBGetCatInf o Get information about a single catalog file entry. 

Using the PBCatSearch function is the fastest and most reliable way to search the 
catalog file of an HFS volume for files and directories satisfyiiig certain criteria. The 
PBCatSearch function returr\s a list of FSSpec records describing titie files or 
directories that match the criteria specified by your application. 

However, PBCatSearch is not available on all volianes or in all versions of the 
File Manager. See ''Determining the Features of the File Manager" on page 2-32 
for instructions on how to determine whether the system software and the target 
volume both support the PBCat Sear ch function. 

Note 

The PBCat Sear ch function is available on all volumes that support the 
AppleTalk Filing Protocol (AFP) version 2.1. This includes volumes and 
directories shared using the file sharing software introduced in system 
software version 7.0 and using the AppleShare 3.0 file server software. ♦ 
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In environments where PBCatSearch is not available, you'll need to do a search that 
recursively descends the directory hierarchy and reads through the catalog entries of all 
files and directories located in each directory in that hierarchy. You can do this by making 
indexed calls to the PBGetCatInf o hmction, which is supported by all system software 
versions and by all volumes. However, using this recursive, indexed search method is 
usually sigruficantly slower than using the PBCatSearch function. (For example, a 
recursive, indexed search that takes over 6 minutes might take about 20 seconds using 
PBCatSearch.) 

See "Searching a Volume" beginning on page 2-38 for examples of using both 
PBCatSearch and PBGetCatInf o to search a volume for files and directories. 

Shared Environments 

Any operating environment that supports multiple users and multiple access to data or 
applications is known as a shared environment. A shared environment can be a number 
of workstations attached to a network as well as a single workstation executing a 
multi-user operating system such as A/UX. 

The File Manager supports access both to locally mounted volumes and to volumes 
located on devices attached to remote machines on a network. For example, AppleShare, 
Apple's file-server application, allows users to share data, applications, and disk storage 
over a network. System software version 7.0 introduced File Sharing, a local version of 
AppleShare that allows users to make some or all of the files on a volume available over 
the network. To do so, a user establishes a volume or directory as a share point, making 
it available for use by registered users or guests on the network. 

It is a virtual certainty that some users will run your application in a shared environment. 
The File Manager, Chooser, and other system software components cooperate to make 
access to remote volumes largely transparent to your application. As a result, most 
applications do not need to accommodate shared environments explicitly. You can read 
and write files, for instance, regardless of whether they are located on a local or a remote 
volimie. 

If your application performs certain operations on files, however, you might be able to 
save considerable time by using special shared environment routines. Suppose, for 
example, that you want to copy a file to another directory on a volume. In the general 
case, you handle this by reading a buffer of data from the source file and then writing it to 
the destination file. If the source and destination volumes are remote, however, this 
tedmique might involve the copying of a lot of data over the network. To optimize remote 
file copying, the File Manager provides the PBHCopyFile function, which copies a 
remote file without sending the data across the network. Similarly, the PBHMoveRename 
function allows you to move and optionally rename a file located on a remote volume. 

The File Manager provides routines that allow you to control other aspects of a shared 
environment, including 

■ providing multiple users with shared read/ write access to files 

■ locking and unlocking byte ranges within a file to ensure exclusive access to data 
during updates 
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■ enabling and disabling sharing on local volumes and directories 

■ getting and setting access privileges for directories 

■ determining volume mounting and login information so that any volume can be 
unmounted and remounted easily 

Table 2-8 lists the File Manager routines that you can use in a shared environment. Note 
that all of these are lov^-Ievel routines. 



Table 2-8 Shared environment routines 


Routine 


Description 


PBHOpenDeny 


wpen a nie s aaia loriv ubuig uic ck-lcoo utuiy iiiutico. 


PBHOpenRFDeny 


wpen a me s resource lorK ubuig me at-cebo ueiiy iiiuueb. 


PBLockRange 


LOCK a pornon or a snarea nie. 


PBUnlockRange 


uniocK a previously loCKea pornon or a bxiareu. nie. 


PBShare 


Establish a volume or directory as a share pomt. 


PBUn share 


Remove a share point from a shared environment. 


PBGetUGEntry 


Get a list of users and groups on the local fQe server. 


PBHGetDirAccess 


Get the access control information for a directory- 


PBHSetDirAccess 


Set the access control information for a directory. 


PBGetVolMountlnfoSize 


Get the size of a volume mounting information record. 


PBGetVolMountlnfo 


Get volume mounting information. 


PBVo 1 umeMoun t 


Mount a volume. 


PBHGetLoglnlnfo 


Get the method used to log on to a shared volume. 


PBHMapID 


Get the name of a user or group from its ID. 


PBHMapName 


Get the ID of a user or group from its name. 


PBHCopyFile 


Copy a file on a remote volume. 


PBHMoveRename 


Move (and perhaps rename) a file on a remote volume. 



The follov^ring sections describe the capabilities provided by these routines. 

Shared File Access Permissions . 

In a shared envirorunent, files can be shared at a file or subfile level. At a file level, a 
project schedule could be read by many users simultaneously but updated by orUy one 
user at a time. At a subfile level, different records of a data base file could be updated by 
several users at the same time. 
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The access modes provided by the standard file-opening routines prove insufficient for 
shared files. Two additional open functions, PBHOpenDeny and PBHOpenRFDeny, allow 
the ability to deny access as well. These deny modes are cumulative, combining to 
determine the current access permissions for a file. For instance, if the first opening 
routine denies reading to others and the second denies writing, both reading and writing 
are then denied for the file. 

Figure 2-1 shows how new access and deny modes are granted or refused according to a 
file's current access and deny modes. An unshaded square indicates that a new open call 
with the listed permissions would succeed; otherwise, the new open call would fail. 



Figure 2-1 Access and deny mode synchronization 




You specify deny modes by setting bits in the ioDenyModes field of the parameter 
block passed to PBHOpenDeny or PBHOpenRFDeny, Cujrrently four bits of this field 
are meaningful: 



Bit Meaning 

0 If set, request read pernussioh 

1 If set, request write permission 

4 If set, deny other users read permission to this file 

5 If set, deny other users write permission to this file 
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The combination of access and deny requests allows four common opening possibilities: 

■ Browsing access. You request browsing access by specifying both read and 
deny-write modes (ioDenyModes set to $0021). Browsing access is traditional 
read-only access; it permits multiple readers but no writers. This access mode is useful 
for shared files that do not change often, such as help files, configuration files, and 
dictionaries. 

■ Exclusive Access. You request exclusive access by specifying both read and write 
access and both deny-read and deny-write access (ioDenyModes set to $0033). Most 
applications that are not specifically designed to share file data use this permission 
setting. An exclusive access opening call succeeds only if there are no existing paths to 
the file. After a successful opening call, all future attempts to establish access paths to 
the file are denied until the exclusive-access path is closed. 

■ Access as a single writer with multiple readers. You request access as the single 
writer with multiple readers by specifying both read and write access and deny-vmte 
access (ioDenyModes set to $0023). This access method allows additional users to 
gain read-only access to browse a document being modified by the initial writer. The 
writer's application is responsible for range locking the file (by calling PBLockRange) 
before writing to it, to prevent reading when the file is inconsistent. 

■ Shared access. You request shared access by specifying both read and write access 
(ioDenyModes set to $0003). Shared access should be used by applications that 
support full multi-user access to its documents. Range locking is needed to prevent 
other users from accessing information imdergoing change. Each user must also check 
for and handle any errors that result from access by other users. You might prefer to 
use a semaphore to flag records in the dociunent as they are checked out, rather than 
use range locldng exclusively. 

You can open a shared file using either the deny modes described here or the file access 
permissions described in "File Manipulation" on page 2-7. If you use the original 
permissions when you open a file located in a shared dirjectory, the File Manager 
translates those permissions iato the corresponding access and deny modes. The basic 
rule followed in this translation is to allow a single writer or multiple readers, but not 
both. The translation from the original permissions to the deny-mode permissions is 
shovm in Table 2-9. 



Table 2-9 



Access mode translation 



HFS permissions 

fsCurPerm . 

f sRdPerm 
f sWrPerm 
f sRdWrPerm 



D^ny-mode permissions 

Exclusive dccess, or browsing access if exdxisive access 
IS imavailable. 

Browsing access. 

Exclusive access. 

Exclusive access, or browsing access if exclusive access 
is imavailable. 



fsRdWrShPerm 



Shared access. 
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Notice that f sCurPerm and f sRdWrPerm are retried as read-only (browsing access) if 
exclusive access is not available. In addition, whenever browsing access is requested 
(that is, when you directly request E sRdPerm, or when a request for f sCur Perm or 
f sRdWrPerm is retried because exclusive access is not available) and cannot be granted, 
the AppleShate external file system searches through the open file control blocks (FCBs) 
for another AFP access path to the file. If an AFP access path to that file is found, a 
read-only access path is returned that shares the AFP access path. 

Directory Access Privileges 

AppleShare allows users to assign directory access privileges to individual directories, 
controlling who has access to the files and folders in the directory. A directory may 
be kept private, shared by a group of registered users, or shared with all users on 
the network. 

Users are organized into groups. Users can belong to more than one group. Information 
about users and their privileges is maintained by AppleShare. Each directory has access 
privileges assigned for each of these three classifications of users: owner, group, and 
everyone. The following privileges can be assigned: 

■ See Folders. A user with this access privilege (also called search privilege) can see 
other directories in the specified directory. 

■ See Files. A user with this access privilege (also called read privilege) can see the 
icons and open documents or applicafions in that directory as well. 

■ Make Changes. A user with this access privilege (also called write privilege) can 
create, modify, rename, or delete any file or directory contained in the specified 
directory. Directory delefion requires additional privileges. It is possible to have Make 
Changes privileges without also having See Folders or See Files privileges; this would 
allow users to put items into a directory but not view the contents of that directory 

For instance, a user might assign privileges to a particular directory allowing the owner 
to read, write, and search the directory, and allowing everyone else (whether in the 
group or not) only to search the directory. 

On directories shared using File Sharing, you can also assign blank access privileges. In 
this case, the File Manager ignores any other access privileges and uses the access 
privileges of the directory's parent. On the local machine, directories in a shared area 
have blank access privileges, until set otherwise. 

Note 

You cannot assign blank access privileges to a volume's root directory. ♦ 
You can use the PBHGetDirAccess and PBHSetDirAccess functions to determine 
and change the access privileges for a directory. The access privileges are passed in the 
4-byte ioACAccess field of the accessParam variant of the HFS parameter block 
passed to these two functions. The 4 bytes are interpreted separately; byte 0 is the 
high-order byte. 
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Byte Meaning 

0 User's access privileges 

1 Everyor\e's access privileges 

2 Group's access privileges 

3 Owner's access privileges 

The bits in each byte encode access privilege iriformation, as illustrated in Figure 2-2. 
(The high-order byte is on top, and the high-order bit is on the left.) Note that the user's 
privileges byte also indicates whether the user owns the directory and whether the 
directory has blank access privileges. 

Figure 2-2 Access privileges information in ttie ioACAccess field 



Directory owner 



Blank access privileges 




User's privileges 
Everyone's privileges 

— Group's privileges 

— Owner's privileges 



Search 



Read 



Write 
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D> 
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CD 



If bit 31 is set, then the user is the owner of the specified directory. If bit 28 is set, the 
specified directory has blank access privileges. If bit 28 is clear, the 3 low-order bits of 
each byte encode the write, read, and search privUeges, respectively. If one of these bits 
is set, the directory privileges permit the indicated access to the specified individual. 
The 3 low-order bits of the byte encoding the user's access privilege information are 
the logical OR of the corresponding bits in whichever of the other 3 bytes apply to the 
user. For example, if the user is the owner of a directory and is in the directory's group, 
then the 3 low-order bits of the user byte are the logical OR of the corresponding bits in 
the other 3 bytes. If, however, the user is not the owner and is not in the directory's 
group, the user privilege bits have the same values as the corresponding ones in the 
everyone byte. 



2-19 

About the File Manager 



TIVO-408469 



CHAPTER 2 



File Manager 



You can use PBHSetDirAccess to set the low-order 3 bits of all the privUeges bytes 
except the user's privUeges byte. In the user's privileges byte, you can set only the blank 
access privileges bit (bit 28) . 

Note 

Not all volumes support blank access privUeges. You can call the 
PBHGetVol Farms hmction to determine whether a particular volume 
supports blank access privileges. ♦ 

Remote Volume Mounting 



Typically, the user mounts remote shared volumes through the Chooser or by opening an 
alias file. The File Manager in system software version 7.0 and later provides a set of caUs 
for collecting the mountmg information from a mounted volume and then usmg that 
information to mount the volume again later, without going through the Chooser. 
Ordinarily, before you can mount a volume programmatically, you must record its 
mounting information while it's mounted. Because the size of the mounting mformation 
can vary, you first call the PBGetVolMountlnfoSize hinction, which returns the 
size of the record you'll need to aUocate to hold the mounting information. You then 
allocate the record and caU PBGetVolMountInf o, passing a pointer to the record. 
When you want to mount the volume later, you can pass the record directly to the 
PBVolumeMount function. 



Note 

The hmctions for mounting volumes programmaticaUy are low-level 
functions designed for specialized appUcations. Even if your appUcahon 
needs to track and access volumes automatically, it can ordmanly use 
the Alias Manager, described in the chapter "Alias Manager" m this 
book. The AUas Manager can record mounting information and later 
remount most volumes, even those that do not support the 
programmatic mounting functions. ♦ 

The programmatic mounting hmctions can now be used to mount AppleShare volumes. 
The hmctions have been designed so that they can evenhially be ^ed to mount local 
Macintosh volumes, such as partitions on devices that support partitionmg, and local or 
remote volumes managed by non-Madntosh file systems. 

Privilege Information in Foreign File Systems 



VirhiaUy every file system has its own privilege model, that is, conyenHons for 
controUing access to stored files and directories. A number of non-Macintosh file systems 
support access from a Macintosh computer by mapping their native privilege models 
onto the model defined by the AppleTalk Filing Protocol (AFP). Most applications that 
manipulate files in foreign file systems can rely on the intervening software to translate 
AFP privileges into whatever is required by the remote system. 
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The correlation is not always simple, however, and some applications require more 
control over the files stored on the foreign system. The A/UX privilege model, for 
example, recognizes four kinds of access: read, write, execute, and search. The AFP 
model recognizes read, write, deny-read, and deny-write access. If a shell program 
nuuiing on the Macintosh Operating System wants to allow the user to set native A/UX 
privileges on a remote file, it has to communicate with the A/UX file system using the 
A/UX privilege model. 

System software version 7.0 provides two new hmctions, PBGetForeignPrivs and 
PBSetForeignPrivs, for manipulating privUeges in a non-Madntosh file system. 
These access-control functions were designed for use by shell programs, such as the 
Finder, that need to use the native privilege model of the foreign file system. Most 
applications can rely on using shared environment functions, which are recognized by 
file systems that support the Macintosh privilege model. The new access-control 
functions do not relieve a foreign file system of the need to map its own privilege model 
onto the shared environment functions. 

Like all other low-level File Manager ftmctions, the access-control functions exchange 
information with your application through parameter blocks. The meanings of some 
fields vary according to the foreign file system used. These fields are currently defined 
for A/UX, and you can define them for other file systems. 

You car\ identify the foreign file system through the PBHCetVolParms function. The 
attributes buffer introduced in system software version 7.0 for the PBHGetVolParms 
function contains a field for the foreign privilege model, vMForeignPrivID. 

Note 

The value of vMForeignPr ivID does not specify whether the remote 
volume supports the AFP access-control functions. You can determine 
whether the volume supports the AFP access-control functions by 
checking the bAccessCnt 1 bit in the vMAttrib field. ♦ 

A value of 0 for vMForeignPr ivID signifies an HFS voliune that supports no foreign 
privilege models. The field currently has one other defined value. 

CONST 

fsUnixPriv = 1; {A/UX privilege model} 

For an updated list of supported models and their constants and fields, contact 
Macintosh Developer Technical Support. 

A volimie can support no more than one foreign privilege model. 

The access-control functions store information in an HFS parameter block of type 

f oreignPrivParaiTt The parameter block can store access-control information in one 

or both of 

■ a buffer of any length, whose location and size are stored in the parameter block 

■ 4 long words of data stored in the parameter block itself 
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The meanings of the fields in the parameter block depend on the definitions established 
by the foreign file system. For example, the A/UX operating system uses the 
ioForeignPrivBuf f er field to point to a 16-byte buffer that describes the access 
rights for the specified file or directory. The buffer is divided into four fields, as follows: 

Bytes Description 

0-3 The user ID of the owner of the file or directory. 

4-7 The group ID of the owner of the file or directory. 

Mode bits specifying the type of access available to the owner of the file or 
directory, the group of the file or directory, and to everyone else. The value in 
this field is a logical OR of some of the following octal values: 



Value 


Meaning 


0001 


Executable by others. 


0002 


Writable by others. 


0004 


Readable by others. 


0010 


Executable by the group. 


0020 


Writable by the group. 


0040 


Readable by the group. 


0100 


Executable by the owner. 


0200 


Writable by the owner 


0400 


Readable by the owner 


2000 


Set group ID on executipn. 


4000 


Set user ID on execution. 



(Execute privileges on a directory mean that the directory is searchable.) You 
can also use these octal masks to test or set common acess rights: 

Mask Meaning 

0007 Executable, writable, and readable by others. 

0070 Executable, writable, and readable by the group. 

0700 Executable, writable, and readable by the owner 

12-15 The active user's access rights. The value in this field is a logical OR of some 
of the following octal values: 

Value Meaning 

0001 Executable by user. 

0002 Writable by user 
0004 Readable by user. 

0010 Set if user owns this file or directory. 

Note that you carmot change the owner of a file or directory using 
PBSetForeignPrivs. Accordingly, the value 0010 is meaningful for 
PBGetForeignPrivs only. 



2-22 



About ttie File Manager 



TIVO-408472 



CHAPTER 2 



File Manager 

File ID Reference Routines 



The File Manager provides a set of three low-level functions for creating, resolving, and 
deleting file ID references. These functions were developed for use by the Alias Manager 
in tracking fUes that have been moved within a volume or renamed. In most cases, you 
should use the Alias Manager, not file IDs, to track files. See the chapter "Alias Manager" 
in this book. 

You establish a file ID reference when you need to identify a file using a file number (see 
"File IDs" on page 2-24). You create a file ID reference with the PBCreateFilelDRef 
function. Because the File Manager assigns file numbers independently on each volume, 
file IDs are not imique across volumes. 

You can resolve a file ID reference by calling the PBResolveFilelDRef hmction, 
which determines the name and parent directory ID of the file with a given ID. If you no 
longer need a file ID, remove its record from the directory by calling the 
PBDeleteFilelDRef fimction. 

Note 

Removing a file ID is seldom appropriate, but the hmction is provided 
for completeness. ♦ 



Identifying Files, Directories, and Volumes 



Whenever you want to perform some operation on a file, directory, or volume, you need 
to identify the target item to the File Manager. Exactly how you specify these items in the 
file system depends on several factors, including which version of system software is 
currendy running and, if the target item is a file, whether it is open or closed. For 
example, once you have opened a file, you subsequendy identify that file tothe FUe 
Manager by providing its file reference number, a unique number returned to your 
application when you open the file. 

In aU other cases, you can identify files, directories, and volumes to the FUe Manager 
by using a variety of methods. In addition to file reference numbers, ti\e File 
Manager recogiuzes 

■ file system specifications 

■ file ID references 

■ directory ID numbers 

■ volume reference niunbers 

■ working directory reference numbers 

■ names and full or partial pathnames 

This section describes each of these ways to identify items in tiie file system. Note, 
however, that some of these metiiods are of historical or tiieoretical interest only. 
Working directory reference numbers exist solely to provide compatibiU^ with die 



2-23 

Identifying Files, Directories, and Volumes 



T/VO-408473 



CHAPTER 2 



File Manager 



now-obsolete Macintosh file system (MFS), and their use is no longer recommended. 
Similarly, the use of fuU pathnames to specify volumes, directories, or files is not 
generally recommended. 

Whenever possible, you should use file system specifications to identify files and 
directories because they provide the simplest method of identification and are 
recognized by the Finder, the Standard File Package, and other system software 
components beginning with system software version 7.0. If your application is intended 
to run in system software versions in which the routines that accept file system 
specification records are not available, you skould use the volume reference number, 
parent directory ID, and name of the item you wish to identify. 

File System Specifications ^ 



Conventions for identifying files, directories, and volumes have evolved as d\e File 
Manager has matured. System software version 7.0 intoduced a simple, standard form 
for identifying a file or directory, called a file system specification. You can use a file 
system specification whenever you must identify a file or directory for the File Manager. 

A file system specification contains 

■ the volume reference number of \he volume on which the file or directory resides 

■ the directory ID of the parent directory 

■ the name of the file or directory 

For a complete description of the file system specification (FSSpec) record, see "File 
System Specification Record" on page 2-86. 

The Standard File Package in system software version 7.0 uses FSSpec records to 
identify files to be saved or opened. The File Manager provides a new set of high-level 
routines that accept FSSpec records as input, so that your appUcation can pass the data 
directly from the Standard FUe Package to the File Manager The Alias Manager and the 
Edition Manager accept file specifications only in the form of FSSpec records. 
The Finder introduced in version 7.0 uses aUas records, which are resolved into FSSpec 
records, to identify files to be opened or printed. 

Version 7.0 also introduced the FSMakeFSSpec hinction, which initializes an FSSpec 
record for a particular file or directory. For a description of FSMakeFSSpec, see 
"Creating File System Specification Records" on page 2-34. 



File IDs 

A file ID is a unique number that the FQe Manager assigns to a file at the time it is 
created. The File Manager uses file IDs to distinguish one file from another on the same 
volume. In fact, a file ID is simply the catalog node ID of a file. As a result, file IDs are 
functionaUy analogous to directory IDs (described in tt\enext section), and both kinds c 
IDs are assigned from the same set of numbers. 
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The File Manager can set up an internal record in the volume's catalog that specifies 
the filename and parent directory ID of the file with a given file ID, allowing you to 
reference the file by that number. (For more information about the volume's catalog, 
see "Catalog Files" on page 2-70.) This internal record in the volunie Catalog is a file ID 
reference (or file lb thread record). 

It is important to distinguish file IDs from file ID references. File IDs exist on all HFS 
volumes, but fOe ID references might or might not exist on a particular HFS volume. 
Even if file ID references do exist on a volume, they might not exist for aU the files on 
that volume. In addition, you can track files by theii* file IDs only on systems capable of 
creating and resolving file ID references. See "File ID Reference Routines" on page 2-23 
for a description of the File Manager functions that allow you to manipulate file IDs. 

Note 

The file ID is a low-level tool and is uiuque only on one HFS volume. In 
most cases, your application should track files using the Alias Manager, 
described in the chapter "Alias Manager" in this book. The Alias 
Manager can track files across volumes. It creates a detailed record 
describing a file that you want to track, and, when you need to resolve 
the retord later, it performs a sophisticated search. The Alias Manager 
uses file IDs internally. ♦ 

A file ID is analogous to a directory ID. A file ID is vmique only within a volimcie and 
remaii\s constant even when the file is moved or renamed. When a file is copied or 
restored from backup, however, the file ID changes. File IDs are uiuque over time— that 
is, once an ID has been assigned to a file, that number is not reused even after the file has 
been deleted. 

The file ID is a permanent file reference, one that a user cannot change. After storing a 
file ID, yovir application can locate a specific file quickly and automatically, even if the 
user has moved or renamed it on the same volume. 

File IDs are intended only as a tool for tracking files, not as a new element in file 
specification conventions. Neither high-level nor low-level File Manager functions 
accept file IDs as parameters. 

Directory IDs ' 

A direttory ID i$ k xmique numbfix that the File Manager uses to distinguish oiie 
directory from anoflier ori the same volume. Assigned by the File Manager when the 
directory is created, a directory ID is simply the catalog node ID of a directory. As a 
result, directory IDs are functionally equivalent to file IDs, and both kinds of IDs are 
assigned from the same set of nimibers. 

Directory IDs are long integers. The File Manager defines several constants to refer to 
special directory IDs that exist on every volume. 

CONST 

fsRtParlD = 1; {directory ID of root directory's parent) 
fsRtDirlD = 2; {directory ID of volume *s root directory) 
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The root directory of every volume has a directory ID of 2. In addition, the root directory 
of every volume has a parent directory ID of 1, There is, however, no such parent 
directory; the constant f sRtParlD is provided solely for use:by applications and File 
Manager routines that need to specify a parent ID when referring to the volume's root 
directory. For example, if you call the PBGetCat Inf o function when the ioDirlD field 
is set to f sRtDirlD, the value f sRtParlD is returned in the ioDrParlD field. 

Volume Reference Numbers 

A volume reference number is a uruque number assigned to a volume at the time it is 
mounted. Unlike the volvmie name (which the user can change at any time and hence 
may not be tmique), the volume reference number is both imique and unchangeable by 
the user, and so is a reliable way to refer to a volume for as long as it is mounted. 

Volume reference nimibers are small negative integers. They are valid ordy tmtil the 
volume is lonmounted. For example, if you place a volume offline and then bring it back 
online, that volume retains the same volume reference number it was originally 
assigned. However, if you unmount a volume and then remount it at some later time, its 
volume reference number might not be the same during both mounts. 

Note 

A volume reference number refers to a volume only as long as the 
volume is moimted. To create a volume reference that remains valid 
across subsequent boots, use alias records. See the chapter "Alias 
Manager" in this book for details. ♦ 

Working Directory Reference Numbers 

The File Manager provides a method of identifying directories known as working 
directory reference niunbers. A working directory is a temporary directory reference 
that the File Manager uses to specify both a directory and the volume on which it 
resides. Each working directory is assigned a working directory reference number at 
the time it is created. You can use this number in place of a volume reference number in 
all File Manager routines. 

Note 

Working directories were developed to allow applications written for 
the now-obsolete Macintosh file system to execute correctly when 
accessing volumes using d\e hierarchical file system. In general, your 
application should not create workirig directories and, in the few 
instances a worldng directory reference number is returned to your 
application, it should immediately convert that number to a volume 
reference ilumber and directory ID. ♦ 

The first file system available on Macintosh computers was the Macintosh file system 
(MPS), a "flat" file system in which all files are stored in a single directory. The 
hierarchical organization of folders within folders is an illusion maintained by the 
system software. As a result, you can identify a file imder MFS simply by specifying its 
name and its volume. Typically, MFS routines require a volume reference number and a 
filename to specify a file. 
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To improve performance, especially with larger volumes, Apple Computer, Inc., intro- 
duced the hierarchical file system (HFS) on the Macintosh Plus computer and later 
models. In HFS, a volume can be divided into smaller units known as directories, which 
can themselves contain files or other directories. This hierarchical relationship of folders 
corresponds to an actual hierarchical directory structure maintained on disk. (See "Data 
Organization on Volumes" beginning on page 2-52 for the precise details of this hierarchi- 
cal directory structure.) 

Each file on an HFS volume is stored in a directory, called the file's parent directory. To 
identify a file in HFS, you must specify its volxmie, its parent directory, and its name. The 
File Manager assigns each directory a directory ID, and the user or the system software 
assigns each directory a name. The HFS File Manager routines include an additional 
parameter to handle the directory specification. 

To keep existing applications runiung smoothly, Apple Computer, Inc. introduced the 
concept of working directories. A working directory is a combined directory and volume 
specification. To make a directory into a working directory, the File Manager establishes 
a working directory control block that contains both the volume and the directory ID of 
the target directory. The File Manager returns a unique working directory reference 
number, which you can use instead of the volume reference number in all routines. 

Note 

If your application provides both a directory ID and a working directory 
reference number, the directory ID is used to specify the directory 
(overriding the working directory specified by the working directory 
reference number). The working directory reference number is used to 
specify the volume (imless a volume name, which overrides all other 
forms of volume specification, is also provided). ♦ 

The best course of action is to avoid using working directories altogether. In the few 
cases where system software returns a working directory reference number to your 
application, tiie recommended practice is to immediately convert that working directory 
reference number into its corresponding directory ID and volume reference number 
(using PBGetWDInf o or its high-level equivalent, GetWDInf o). 

In system software versions 7.0 and later, the Process Manager closes all working 
directories opened on behalf of your application when it terminates (quits or crashes). 
If your application might also run imder earlier system software versior\s, you need to 
be careful to dose any such working directories before you quit (using PBCloseWD or 
its high-level equivalent, CloseWD). 

Names and Pathnames 

Volumes, directories, and files all have names. A volume name is any sequence of 1 
to 27 characters, excluding colons (:), that is assigned to a volume. File and directory 
names consist of any sequence of 1 to 31 characters, excluding colons. You can use 
uppercase and lowercase letters in names, but the File Manager ignores case when 
comparing niames. The File Manager does not, however, ignore diacritical marks when 
comparing names. 
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Although it is legal to use any character other than the colon in file, 
directory, and volume names, you should avoid using nonprinting 
characters in such names, even for temporary files that do not appear on 
the desktop or in the Standard File Package dialog boxes. A program 
written in C interprets a null character (ASCII code $00) as the end of a 
name; as a result, embedding the null character in a filename is likely to 
cause problems. In addition, file, directory, or volume names with null 
characters are not usable by AFP file servers (such as computers running 
Macintosh File Sharing or AppleShare software). In general, you should 
ensure that you use only printing characters in names of objects that you 
create in the file system. ♦ 

Files and directories located, in the same directory must all have unique names. 
However, there is no requirement that volumes have unique names. It is perfectly 
acceptable for two mounted volumes to have the same name. This is one reason why 
your application should use volume reference numbers rather than volume names to 
specify volumes. 

You can also specify files and directories using pathnames, although this method is 
discouraged. There are two kinds of pathnames, full and partial. A full pathname is a 
sequence of directory names, separated by colons, starting from the root directory (or 
volume) and leading down to the file. A full pathname to the file "Bananas," for instance, 
might be something like this: 

MyVolume : Fruits : Tropical : Bananas 

A partial pathname is a pathname that begins in some directory other than the root 
directory. A particular directory is specified by volume reference number (in the case of 
the root directory), working directory reference number, or directory ID, and the 
pathname begins relative to that directory If the directory "Fruits" were specified, for 
instance, the partial pathname to the "Bananas" file would be 

: Tropical : Bananas 

The use of pathnames, however, is highly discouraged. If the user changes names or 
moves things around, they are worthless. It's best to stay with simple file or directory 
names and specify the directoiy containing the file or directory by its directory ID. 

HFS Specifications • 

The simplest way to identify a mounted volume is by giving its volume reference 
nimiber. The simplest way to identify a file or directory located on a mounted volume is 
by providing a file system specification. In some cases, however, you might not be able 
to use file system specifications. 

For example, the low-level File Manager routines do not accept file system specifications, 
and so you must specify files and directories by some other method. You must also use 
another file-identificafion method when you use the high-level HFS routines that existed 
prior to the introduction of the routines that accept FSSpec records as file or directory 

2-28 Identifying Files, Directories, and Volumes 



TIVO-408478 



CHAPTER 2 



File Manager 



specifications. This section summarizes the conventions the File Manager uses to 
interpret the various volume, directory, and file specifications that are available even 
when file system specifications are not. 

The File Manager recognizes three kinds of file system objects: files, directories, and 
volumes. You can identify them using various methods. 

Object Method of identification 

File Filename 
Directory Directory name " 
Directory ID 

Working directory reference number, 
which also implies a volume 

Volume Volume name 

Volume reference number 

Working directory reference number, 
which also implies a directory 

In HFS, you can pass a complete file specification in any of several ways: 

■ full pathname 

■ volume reference number and partial pathname 

■ working directory reference niunber and partial pathname 

■ volume reference number, directory ID, and partial pathname 

A full pathname consists of the name of the volume, the names of all directories between 
the root directory and the target, and the name of the target. A full pathname starts with 
a character other than a colon and contains at least one colon. If the first character is a 
colon, or if the pathname contains no colons, it is a partial pathriame. If a partial 
pathname starts with the name of a parent directory, the first character in the pathname 
must be a colon. If a partial pathname contains only the name of the target file or 
directory, the leading colon is optional. 

You can identify a volume in the vRef Num parameter by volume reference nimiber or 
drive number, but voliune reference number is preferred. A value of 0 represents the 
default Volume. A volume name in the pathi\ame overrides any other volume 
spedfication. Unlike a voltmie name, a volume reference nimiber is guaranteed to be 
uriique. It changes, however, each time a voltime is mounted. 

A working directory reference number represents both the directory ID and the volume 
reference ntunber. If you specify any value other than 0 for the dirlD parameter, that 
value overrides the directory ID implied by a working directory reference nimiber in the 
volume parameter. The volume specification remains valid. 

Figure 2-3 illush-ates the standard ways to identify a file in HFS. 
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Figure 2-3 Identifying a file in HFS 
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Search Paths 

Whenever you specify a value of 0 for the directory ID in an HFS specification, the File 
Manager first looks for the desired file in the directory indicated by the two other 
relevant HFS parameters or fields— namely, the pathname and the volume specification. 
If the specified file is not found in that directory, the File Manager continues searching 
for the file along a path known as the poor man's search path. You need to be aware of 
this behavior so that you do not accidentally open, delete, or otherwise manipulate the 
wrong file. 

Note 

The File Manager uses the poor man's search path only when the 
directory ID parameter or field has the value 0. You can avoid the 
consequences of accidentally opening or deleting the wrong file by 
specifying a directory explicitly with its directory ID. ♦ 

If the volume specification is a working directory reference number, the File Manager 
searches in the directory whose directory ID is encoded in that working directory 
reference number. If the volume specification is a volume reference number or 0, the File 
Manager searches Ln the default directory on the indicated volume. (See "Manipulating 
the Default Volume and Directory" on page 2-35 for information about default 
directories.) If you provide a full pathname, the File Manager searches in the directory 
whose name is contained in the pathname. 

If the File Manager cannot find the specified file in the first directory it searches, it next 
searches the root directory of titie boot volume, but only if the first directory searched is 
located on the boot volume. If the specified file is still not f otmd, or if the first directory 
searched is not located on the boot volume, the File Manager next searches the System 
Folder, if one exists, on the volume containing the first directory searched. If the file still 
carmot be found, the FOe Manager gives up and returns the result code f nf Err (file not 
foimd) to your application. 

As you can see, the use of the poor man's search path might lead to unexpected results. 
Suppose, for example, that you call the HOpenDF function like this: 

myErr := HOpenDF(0, 0, ':Ackees', fsRdWrPerm, myRefNum) ; 

The values c^f 0 for the first two parameters (the volume specification and directory ID) 
indicate that you want the File Manager to look fcwr the named file in the default 
directory. If, however, there is no sudti file in that directory, die File Manager continues 
looking along the poor man's search path for a file vnth the specified name. The result 
might be that you open the wrong file. (Worse yet, if you had called HDelet e instead of 
HOpenDF, you rrught have deleted the wrong file!) 

The File Manager uses the poor man's search path for all routines that can return the 
f nf Err result code and to which you passed a directory ID of zero. It does not use the 
poor man's search path when you specify a nonzero directory ID or when you call an 
indexed routine (that is, when the ioFDirlndex field of the parameter block has a 
nonzero value). The File Manager also does not use the poor man's search path when 
you create a file (perhaps by calling PBHCr eat e) or move a file between directories (by 
caUing PBCatMove). 
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Note 

The poor man's search path might not be supported in future versions of 
system software. You should not depend on its availability. ♦ 



Using th e File Manager 

You can use the File Manager to manipulate files, directories, and volumes. The chapter 
"Introduction to File Management" in this book shows how to use the File Manager and 
other system software services to accomplish the most common file-related operations 
(that is, handling the typical FUe menu commands). This section shows how to accomplish 
a variety of other operations on files, directories, and volumes. In particular, this section 
shows how to 

■ determine the available features of the File Manager 

■ determine the characteristics of a particular mounted volume 

■ create file system specification records 

■ manipulate the default volume and directory 

■ delete files and file forks 

■ search a volume fpr files or directories matching various criteria 

■ construct the full pathname of a file 

■ determine the amount of free space on a volume 

■ lock and unlock byte ranges in shared files 

Altogether, the code listings given in this section provide a rich source of information 
about using the many File Manager routines and data structures. 

Determining the Features of the File Manager 

Some of the capabilities provided by the File Manager depend on the version of. system 
software that is running, and some others depend on the characteristics of the target 
volume. For example, the routines that accept FSSpec record^ as file or directory 
specifications were introduced in system software version 7.0 and are unavailable in 
earlier system software versions— unless your software development system provides 
"glue" that allows you to call those routineis when running in earlier system software 
versions (or uiUess some system extension provides ti:\ose routines). Similarly, some 
volumes support features that other volumes do not; a volume that has local file 
sharing enabled, for instance, allows you to lock byte ranges in any files on a volume 
that is sharable. 

Before using any of the File Manager features that are not universally available in all 
system software versions and on all volumes, you should check for that feature's 
availability by calling either the Gestalt function or the PBHGetVolParms function, 
according to whether the feature's presence depends on the system software or the 
characteristics of the volume. 
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You can use Gestalt to determine whether or not you can call the functions that accept 
and support FSSpec records. Call Gestalt with the gestaltFSAttr selector to check 
for File Manager features. The response parameter currently has two relevant bits: 

CONST 

gestaltFullExtFSDispatching = 0; {exports HFSDispatch traps} 
gestaltHasFSSpecCalls = 1; {supports FSSpec records} 

Constant descriptions 

gestaltFullExtFSDispatching 

If set, all of the routines selected through the _HFSDispatch trap 
are available to external file systems. If this bit is clear, the File 
Manager checks the selector passed to _HFSDispatch and ensures 
that it is valid; if the selector is invalid, the result code paramErr is 
returned to the caller. If this bit is set, no such validity checking is 
performed. 

gestaltHasFSSpecCalls 

If set, the operating environment provides the file system 
specification versions of the basic file-manipulation functions, plus 
the FSMakeFSSpec function. 

The chapter "Introduction to File Management" in this book iUustrates how to use the 
Gestalt function to determine whether the operating environment supports the 
routines that accept FSSpec records. For a complete description of the Gestalt 
function, see the chapter "Gestalt Manager" in Inside Macintosh: Operating System Utilities. 

To test for the availability of the features that depend on the volume, you can call the 
low-level function PBHCetVolParms. Listing 2-1 illustrates how you can determiiie 
whether the PBCat Search function is available before using it to search a volume's 
catalog. Note that the Support sCatSearch function defined in Listing 2-1 first calls 
Gestalt to determine whether the File Manager supports PBCat Search. If it does, the 
Support sCat Search function calls PBHGetVolParms to see if the indicated volume 
also supports PBCat Sear ch. 

^ Listing 2-1 Testing for PBCat Search 

FUNCTION SupportsCat Search (vRefNum: Integer) : Boolean ; 
VAR 

itiyHPB: HParamBlockRec ; 

inf oBuf f er : GetVolParmsInf oBuf f er ; 
attrib: Longint; 
BEGIN 

SupportsCat Search := FALSE; {assume no PBCatSearch support} 
IF gHasGestalt THEN {set this somewhere else} 

IF Gestalt (gestaltFSAttr, attrib) = noErr THEN 

IF BTst (attrib, gestaltFullExtFSDispatching) THEN 
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BEGIN {this File Mgr has PBCatSearch} 

WITH myHPB DO 
BEGIN 

ioNamePtr := NIL; 
ioVRefNum := vRefNum; 
ioBuffer := @infoBuffer; 
ioReqCount := SIZEOF ( inf oBuf f er) ; 
END; 

IF PBHGetVolParms(@inyHPB, FALSE) = noErr THEN 

IF BTST(infoBuf fer.vMAttrib, bHasCatSearch) THEN 
SupportsCatSearch := TRUE; 

END; 

END; 

The SupportsCatSearch function calls PBHGetVolParms for the volume whose 
reference number is passed as a parameter to SupportsCatSearch. The 
PBHGetVolParms function returns information about a volume in a record of type 
GetVolParmsInf ©Buffer. The vMAttr ib field of that record contains a number of 
bits that encode information about the capabilities of the target volume. In particular, the 
bit bHasCatSearch is set if the specified volume supports the PBCatSearch function. 

Note 

Some features of voliunes might change dynamically during the 
execution of your application. For example, the user can turn File 
Sharing on and off, thereby changing the capabilities of volumes. See 
"Locking and Unlocking File Ranges" on page 2-50 for more details. ♦ 

Creating File System Specification Records 

Sometimes it is useful for your application to create a file system specification record. For 
example, your application might be running in an environment where the enhanced 
Standard File Padcage routines (which return FSSpec records) are unavailable but the 
Ffle Manager routines that accept FSSpec records are available (perhaps as glue code in 
your development system). You can call the FSMake FSSpec function (or its low-level 
equivalent PBMakeFSSpec) to initialize a file system specificntion record. 

Three of the parametiers to FSMakeFSSpec represent the volume, parent directory, and 
file specifications of the target object. You can provide this information in any of the four 
combinations described in "HFS Specifications" beginning on page 2-28. Table 2-10 
details the ways your applicatioix can identify the name and location of a file or directory 
in a call to FSMakeFSSpec. 

The fovirth parameter to FSMakeFSSpec is a pointer to the FSSpec record. 
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Table 2-10 How FSMakeFSSpec interprets its parameters 



vRefNum 
Ignored 

Volume reference 
number or drive 
number 

Working directory 
reference number 



Volume reference 
number or drive 
number 

Working directory 
reference number 



Volume reference 
number of drive 

Working directory 
reference number 



Volume reference 
number or drive 
number 

0 



dirlD 
Ignored 
Directory ID 

Directory ID 



Directory ID 
0 

0 

Directory ID 
Oirectory ID 
0 
0 



fileName 
Full pathname 
Partial pathname 

Partial pathname 



Partial pathname 



Partial pathname 



Empty string 
or NIL 

Empty string 
or NIL 



Empty string 
or NIL 



Empty string 
or NIL 

Partial pathname 



Empty string 
or NIL 

Partial pathname 



Interpretation 

Full pathname overrides any other information 

Partial pathname starts in the directory whose 
parent is specified in the dirlD parameter 

Directory specification in the dir ID parameter 
overrides the directory implied by the 
reference number 

Partial pathname starts in the directory w^hose 
parent is specified in dir ID 

Partial pathname starts in the root directory of 
the volume in vRef Num 



Partial pathname starts in the directory 
specified by the v^^orking directory 
reference number 

The target object is the directory specified by 
the directory ID in di r ID 

The target object is the directory specified by 
the working directory reference number 
in vRef Num 

The target object is the volume specified 
in vRef Num 



The target object is the directory specified in 
dir ID on the default volume 

Partial pathname starts in the directory 
specified in dir ID on the default volume 

The target object is the default directory on the 
default volume 

Partial pathname starts in the default directory 
on the default volume 



Manipulating the Default Volume and Directory . 

When your application is running, the File Manager maintains a default voltune and a 
default directory for it. The default directory is used in FUe Manager routines whenever 
you don't explicitly specify some directory. The default volume is the volume containing 
the default directory. 

If you pass 0 as the volume specification with routines that operate on a volume (such as 
mounting or ejecting routines), the File Manager assumes that you want to perform the 
operation on the default volume. Initially the volimie used to start up the application is 
set as the default volume, but your application can designate any moimted volume as 
the default volume. 
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With routines that access files or directories, if you don't specify a directory and you pass 
a volume spedficatiori of 0, the FUe Mariager assumes that the file or directory is located 
ii^ the default dii^ctory. IiutiaUy, the default directory is set to the root duectory of the 
default volume, but your application can designate any directory as the defauh directory. 

Note 

Don't confuse the default directory and volume mamtamed by the 
FQe Manager with the current directory and volume mamtamed by 
the Standard FUe Package. Although the default volume and current 
volume are initially the same, they can differ whenever your appUcation 
resets one of them. See the chapter "Standard File Package m this book 
for more information about the current directory and volume. ♦ 
The provision of a default volume was originally intended as a convenient way for 
you to limit all File Manager calls to a particular volume. The default directory was 
introduced along with HFS as an analog to the default volume. In general, however, it 
is safest to specify both a volume and a directory explicitly in all File Manager calls In 
particular, the introduction of file system specification records has rendered default 
volumes and directories largely obsolete. As a result, you should avoid relymg on them. 
In some cases, however, you might want to set the default volume or directory explicitly 
You can determine the default volume and directory by calling the GetVol or HGetVol- 
function. You can explicitly set the default directory and volume by callmg the SetVol 
or HSetVol function. For reasons explained later, however, the use of HSetVol and its 
low-level equivalent PBHSetVol is discouraged. 

To set the default volume only, you can call SetVol, passing it the volume reference 
number of the volume you want to establish as the default volume, as in this example: 

ittyErr := SetVol (NIL, myVRefNum) ; 

You can instead specify the volume by name, but because volume names might not be 
unique, it is best to use the volume reference number. 

To set both the default directory and the default volume, you could call HSetVol, 
passing it the appropriate volume reference number and directory ID, as in this example: 

myErr := HSetVoKNIL, xnyVRefNum, inyDirlD) ; 

However, using HSetVol cari lead to problems in certain circumstances. When you call 
HSetVol (or its low-level version PBHSetVol) and pass a working directory reference 
number in the vRef Num parameter, the File Manager stores the encoded volume 
reference number and directory ID separately. If you later call GetVol (or its low-level 
version PBGetVol), the FUe Manager returns that volume reference number, not the 
working directory reference number you passed to HSetVol. The net r^ult is that any 
. code using the results of the GetVol caU will access the root directory of the default 
volume, not the actual default directory. 
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It is important to realize that calling HSetVol is perfectly safe if all the code executing in 
your application's partition always calls HGetVol instead of GetVol. This is because 
HGetVol returns a working directory reference number whenever the previous call to 
HSetVol passed one in. Calling HSetVol can create problems only if your application is 
running under a system software version prior to version 7.0. In that case, a desk accesso- 
ry might be opened in your application's partition, thereby inheriting your application's 
default volume and directory. If that desk accessory calls GetVol instead of HGetVol, it 
might receive a volume reference number when it expects a working directory reference 
number, as described in the previous paragraph. To avoid this problem, you can simply 
use SetVol (or PBSetVol) instead of HSetVol, as in this example: 

myErr := SetVol (NIL, myVRefNuni) ; 

In this case, the myVRef Num parameter should contain a working directory 
reference number. 



Deleting Files and File Forks 



You can delete a file by calling FSpDelete, HDelete, or PBHDelete. These functions 
delete both forks of a file by removing the catalog entry for the file and adjusting the 
volume iiiformation block and volume bitmap accordingly. These fimctions do not 
actually erase the disk areas occupied by the file, so there is a reasonable chance that a 
good disk utility might be able to salvage a deleted file if the user hasn't allocated any 
new file blocks in the meantime. 

Sometimes you might want to truncate just one fork of a file. Listing 2-2 illustrates how 
you can truncate a file's resource fork while preserving the data fork. 



Listing 2-2 Deleting a file's resource fork 



FUNCTION TruncateRF (myFileSpec : FSSpec) : OSErr; 

VAR - 1 

myErr: OSErr; {result code) 

myFile: Integer; {file reference number) 

BEGIN 

myErr := FSpOpenRF (myFileSpec, fsRdWrPerm, myFile); 
IF myErr = noErr THEN 

myErr := SetEOF (myFile, 0); 
IF myErr = noErr THEN 

myErr := FSGlose (myFile) ; 
IF myErr = noErr THEN 

myErr := FlushVol (myFileSpec .vRef Num) ; 
TruncateRF := myErr; 
END; 
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The function TruncateRF defined in Listing 2-2 opens the file's resource fork with 
exclusive read/write permission and sets its logical end-of-file to 0. This effectively 
releases all the space occupied by the resource fork on the volume. Then TruncateRF 
closes the file and updates the volume. 

Searching a Volume 

To search a volume efficiently, you can use the PBCat Search function. The 
PBCatSearch function looks at all entries in the volume's catalog file and rehims a list 
of all fUes or directories that match the criteria you specify. You can ask PBCatSearch to 
match files or directories using many types of criteria, including 

■ names or partial names 

■ file and directory attributes 

■ Finder information 

■ physical and logical file length 

■ creation, modification, and backup dates 

■ parent directory ID 

Like all low-level File Manager fimctions, PBCatSearch exchanges information with 
your application through a parameter block. The PBCatSearch function uses the 
csParam variant of the basic parameter block defined by the HParamBlockRec data 
type- That variant includes two fields, ioSearchInf ol and ioSearchlnf o2, that 
contain the addresses of two catalog information records (of type CInf oPBRec). You 
specify which kinds of files or directories you want to search for by filling in the fields of 
those two records. 

The fields in ioSearchlnf ol and ioSearchlnf o2 have different uses: 

■ The ioNamePtr field in ioSearchlnf ol holds a pointer to the target string; the 
ioNamePtr field in ioSearchlnf g2 must be NIL. (If you're not searching for the 
name, the ioNamePtr field in ioSearchlnf ol must also be NIL.) 

■ The date and length fi^elds in ioSearchlnf ol hold the lowest values in the target 
range, and the date and length fields in ioSearchlnf o2 hold ttie hijghest valueis in 
the target range. The PBCatSearch function looks for values greater than or equal to 
the field values in ioSearchlnf ol and less than or equal to the values iri 
ioSearchInfo2. 

■ The ioFlAttr ib and ioFlFndr Inf o fields in ioSearchlnf ol hold the target 
values, and the same fields in ioSearchlnf o2 hold masks that specify which bits 
are relevant. 

Some fields in the catalog information records apply only to files, some only to 
directories, and some to both. Some of the fields that apply to both have different names, 
depending on whether the target of the record is a file or a directory. The PBCatSearch 
function uses only some fields in the catalog information record. Table 2-11 lists the fields 
used for files. 

Table 2-12 lists the fields in catalog information records used for directories. 
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Table 2-11 Fields in ioSearchInf ol and ioSearchinf o2 used for a file 



Field 




Meaning in IoSearchinf ol 


Meaning in IoSearchinf o2 


ioNamePtr 




Pointer to filename 


Reserved (must be NIL) 


ioFlAttrib 




Desired file attributes 


Mask for file attributes 


ioFlFndrlnfo 


Desired Finder information 


Mask for Finder information 


ioFlLgLen 




Smallest logical size of data fork 


Largest logical size 


ioFlPyLen 




Smallest physical size of data fork 


Largest physical size 


ioFlRLgLen 




Smallest logical size of resource fork 


Largest logical size 


ioFlRPyLen 




Smallest physical size of resource fork 


Largest physical size 


ioFlCrDat 




Earliest file creation date 


Latest file creation date 


ioFlMdDat 




Earliest file modification date 


Latest file modification date 


ioFlBkDat 




Earliest file backup date 


Latest file backup date 


ioFlXFndrInf o 


Desired extended Finder information 


Mask for Finder information 


ioFlParlD 




Smallest directory ID of file's parent 


' Largest parent directory ID 




Table 2-12 Fields in ioSearchinf ol and ioSearchinf o2 used for a directory 


Field 




Meaning in IoSearchinf ol 


Meaning in IoSearchinf o2 


ioNamePtr 




Pointer to directory name 


Reserved (must be NIL) 


ioFlAttrib 




Desired directory attributes 


Mask for directory attributes 


ioDrUsrWds 




Desired Finder information 


Mask for Finder information 


ioDrNmFls 




Smallest number of files in directory 


Largest number of files 


ioDrCrDat 




Earliest directory creation date 


Latest creation date 


ioDrMdDat 




Earliest directory modification date 


Latest modification date 


ioDrBkDat 




Earliest directory backup date 


Latest backup date 


ioDrFndrlnfo 


Desired extended Finder information 


Mask for Finder information 


ioDrParlD 




Smallest directory ID of directory's parent 


Largest parent directory ID 




The PBCat Search function seaniies only on bits 0 and 4 in the file attributes 




field (ioFlAttrib). 






Bit 


Meaning 






0 


Set if the file or directory is locked. 






4 


Set if the item is a directory. 





Note 

The PBCatSearch function cannot use the additional bits returned in 
the ioFlAttrib field by the PBGetCatInf o function. ♦ 
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To give PBCat Search a fuU description of the search criteria, you pass it a pair of 
catalog information records that determine the limits of the search and a mask that 
identifies the relevant fields within the records. You pass the mask in the 
ioSearchBits field in the PBCatSearch parameter block. To determine the value of 
ioSearcheits, add the appropriate constants. To match all files and directories on a 
volimie (including the volume's root directory), set ioSearchBits to 0. 

CONST 



f sSBPartialName 


= 1; 


{substring of name} 


fsSBFullName 


= 2; 


{full name} 


fsSBFlAttrib 


= 4; 


{directory flag; software lock flag} 


f sSBNegate 


= 16384; {reverse match status} 


{for files only} 






fsSBFlFndrlnfo 


= 8; 


{Finder file info} 


f sSBFlLgLen 


= 32; 


{logical length of data fork} 


f sSBFlPyLen 


= 64; 


{physical length of data fork} 


f sSBFlRLgLen 


= 128; 


{logical length of resource fork} 


fsSBFlRPyLen 


= 256; 


{physical length of resource fork} 


fsSBFlCrDat 


= 512; 


{file creation date} 


fsSBFlMdDat 


= 1024; 


{file modification date} 


fsSBFlBkDat 


= 2048; 


{file backup date} 


fsSBFlXFndrlnfo 


= 4096; 


{more Finder file info} 


fsSBFlParlD 


= 8192; 


{file's parent ID} 


{for directories 


only} 




fsSBDrUsrWds 


= 8; 


{Finder directory info} 


f sSBDrNmFls 


= 16; 


{number of files in directory} 


f sSBD'rCrDat 


= 512; 


{directory creation date} 


fsSBDrMdDat 


= 1024; 


{directory modification date} 


fsSBDrBkDat 


= 2048; 


{directory backup date} 


f sSBDrFndrlnfo 


= 4096; 


{more Finder directory info} 


f sSBDrParlD 


= 8192; 


{directojT/* s parent ID} 



For example, to isear ch for a file that was creatied between two specified dates and whose 
name contaiiisa specified striiig, set ioSearchBits to 517 (that is, to f sSBFlAttr:ib 
+ f sSBFlCrDat + f sSBPartialName). 

A catalog entry must meet all of the specified criteria to be placed in the list of matches. 
After PBCatSearch has completed its scan of each entry, it checks the f sSBNegate bit. 
If that bit is set, PBCatSearch reverses the entry's match status (that is, if the entry is a 
match but the f sSBNegate bit is set, the entry is not put in the list of matches; if it is not 
a match, it is put in the list). 

Note 

The f sSBNegate bit is ignored during searches of remote volumes that 
support AFP version 2.1. ♦ 
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Although using PBCatSearch is significantly more efficient than searching the 
directories recursively, searching a large volume can still take long enough to affect user 
response time. You can break a search into several shorter searches by specifjnng a 
maximum length of time in the ioSearchTime field of the parameter block and 
keeping an index in the ioCatPosition field. The PBCatSearch function stores its 
directory-location index in a catalog position record, which is defined by the 
CatPositionRec data type. 

TYPE CatPositionRec = {catalog position record) 

RECORD 

initialize: Longint; {starting point) 

priv: ARRAY(1..6] OF Integer; {private data) 

END; 

To start a search at the beginning of the catalog, set the initialize field to 0. When 
PBCatSearch exits because of a timeout, it updates the record so that it describes the 
next entry to be searched. When you call PBCatSearch to restime the search after a 
timeout, pass the entire record that was returned by the last call. PBCatSearch returns a 
list of the names and parent directories of all files and directories that match the criteria 
you specify. It places the list Ln an array pointed to by the ioMatchPtr field. 

Note 

The ioSearchTime field is not used by AFP volumes. To break up a 
potentially lengthy search into smaller searches on AFP volumes, use 
the ioReqMatchCount field to specify the maximum number of 
matches to return. ♦ 

Listing 2-3 illustrates how to use PBCatSearch to find all files (not directories) whose 
names contain the string "Temp" and that were created within the past two days. 



Listing 2-3 Searching a volume with PBCatSearch 



CONST 

kMaxMatches 

kOptBuf ferSize 
VAR 

ni^Err: OSErr; 
myCount : Integer ; 
rayFName: Str255; 
rayVRefNum: Integer; 
myDirlD: Longint; 
nr/CurrDate : Longint ; 
twoDay sAgo : Longint ; 
myPB: 
myMatches 



30; 

$4000; 



HParamBlockRec ; 
PACKED ARRAY [1. 



{find up to 30 matches in one pass) 
{use a 16K search cache for speed) 

{result code of function calls} 
{loop control variable} 
{name of string to look for} 
{volume to search} 
{ignored directory ID for HGetVol} 
{current date, in seconds} 
{date two days ago, in seconds} 
{parameter block for PBCatSearch} 
.kMaxMatchesl OF FSSpec; 
{put matches here} 
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mySpecl: CInfoPBRec; {search criteria, part 1} 

inySpec2: CInfoPBRec; {search criteria, part 2} 

myBuffer: PACKED ARRAY [1. .kOpt Buffers ize] OF Char; 

{search cache} 

done: Boolean; {have all matches been found?} 

PROCEDURE SetupForFirstTime; 
BEGIN 

myErr := HGetVol(NIL, myVRefNum, myDirlD) ; 

{search on the default volume} 



my FName : = ' Temp ' ; 
GetDateTime(myCurrDate) ; 
twoDaysAgo := my Cur r Date - 
WITH myPB DO 
BEGIN 

ioCompletion 

ioNamePtr 

ioVRefNum 

ioMatchPtr 



(2 



24 



{search for "Temp" } 
{get current time in seconds} 
60 * 60); 



= NIL; 
= NIL; 

= myVRefNum; 



ioReqMatchCount : = kMaxMatches ; 
ioSearchBits := f sSBPartialName 
+ fsSBFlAttrib 
+ fsSBFlCrDat; 
@mySpecl; 



@mySpec2; 
0; 



ioSearchlnfol 
ioSearchInf o2 
ioSearchTime 

ioCat Posit ion. initialize := 0; 
ioOptBuffer := ©myBuffer; 
ioOptBufSize := IcOptBuf f erSize; 
END; 

WITH mySpecl DO 
BEGIN 

ioNamePtr := @myFName; 
ioFlAttrib := $00; 
ioFlCrDat := twoDaysAgo; 
END; 

WITH mySpec2 DO 
BEGIN 

ioNamePtr := NIL; 

ioFlAttrib := $10; 

ioFlCrDat := myCurrDate; 
END; 
END; 



{no completion routine} 
{no volume name; use vRefNum} 
{volume to search} 
FSSpecArrayPtr (@myMatches) ; 

{points to results buffer} 
{number of matches} 
{search on partial name} 
{search on file attributes} 
{search on creation date} 
{points to first criteria set} 
{points to second criteria set} 
{no timeout on searches} ■ ' 
{set hint to 0} 
{point to search cache} 
{size of search cache} 



{point to string to find} 
{clear bit 4 to ask for files} 
{lower bound of creation date} 



{set to NIL} 

{set mask for bit 4} 

{upper bound of creation date} 
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BEGIN 

SetupForFirstTime; {initialize data records} 

REPEAT 

myErr := PBCatSearchSync (QmyPB) ; {get some files} 
done := (myErr = eofErr) ; {eofErr returned when all done} 

IF ((myErr = noErr) I done) & (myPB. ioActMatchCount > 0) THEN 
FOR myCount := 1 TO my PB. ioActMatchCount DO 
Writeln(myMatches(myCount] .name) ; 

{report all matches found} 

UNTIL done; 
END; 

When PBCat Search is not avaUable in the current operating environment or is not 
supported by the volume you wish to search, you'll need to use PBGetCat Inf o to 
perform a recursive, indexed search through the volume's directory hierarchy. This 
kind of search is usually much slower than a search with PBCatSearch, and you 
can encounter problems you avoid by using PBCatSearch. For example, a 
recursive, indexed search can require a large amount of stack space. The procedure 
EnumerateShell defined in Listing 2-4 is designed to mininuze the amount of stack 
space used. As a result, it should execute even in envirorunents with very limited 
stack space. 

Listing 2-4 Searching a volume using a recursive, indexed search 



PROCEDURE EnumerateShell (vRefNum: Integer; dirlD: LongInt) ; 
VAR 

rnyName: Str63; 
niyCPB: CInfoPBRec; 
myErr: OSErr; 

PROCEDURE EnumerateCatalog (dirlD: LongInt) ; 
CONST 

kFolderBit = 4; 

VAR 

index: Integer; 

BEGIN 

index := 1; 
REPEAT 

WITH myCBP DO 
BEGIN 

ioFDirXndex := index; 

ioDrDirlD := dirlD; {reset dirlD; PBGetCatlnfo may. change it} 

ioACUser := 0; 
END; 

myErr := PBGetCatlnfo (Qm^^CPB, FALSE); 
IF mr/Err = noErr THEN 
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IF BTst (myCPB.ioFlAttrib, kFolderBit) THEN 
BEGIN {we have a directory} 

{Do something useful with the dir. information in myCPB.) 
EnumerateCatalog (myCPB. ioDrDirlD) ; 

my Err := noErr; {clear error return on way back} 

END 
ELSE 

BEGIN (we have a file} 

{Do something useful with the file information in myCPB.} 
END; 

index : = index + 1 ; 
UNTIL (myErr <> noErr) ; 
END; {EnumerateCatalog} 
BEGIN {EnumerateShell} 
WITH myCPB DO 
BEGIN 

ioNamePtr := ©myNarne; 
i o VRe f Num : = vRe f Num ; 
END; 

EnumerateCatalog (dir ID) ; 
END; {EnumerateShell} 

The EnumerateShell procedure sets up a catalog information parameter block with a 
pointer to a string variable and the volume reference number passed to it. It then calls 
the EnumerateDir procedure, which uses indexed calls to PBGetCatInf o to read the 
catalog information about all items in the specified directory. If an item is a directory (as 
indicated by the kFolderBit bit of the ioFlAt t r ib field of the parameter block), 
EnumerateDir calls itself recursively to enumerate the contents of that directory If an 
item is a file, EnumerateDir performs whatever processing is appropriate- 
Note that EnumerateDir resets the ioDrDirlD field before calling PBGetCatInf o. 
This is necessary because PBGetCatInf o returns a file ID number in that field if the 
item is a file. The EnumerateDir procedure also clears the ioACUser field. You need to 
do this if your search depends on the value in that field after the call to PBGetCatInf o, 
because the value returned in that field for local volumes is meaningless. 

To search an entire volume, call the EnumerateShel 1 procedure with the vRef Num 
parameter set to the volume reference number of the volume you want to search and the 
dir ID parameter set to f sRtDirlD. You can also do a partial search of a volume by 
specifying a different directory ID in the dir ID parameter. 

Constructing Full Pathnames 

As indicated in "Names and Pathnames" on page 2-27, the use of full or partial 
pathnames is strongly discouraged. Full pathnames are particularly unreliable as a 
means of identifying files or directories within your application, largely because the user 
can change the name of any element in the path at virtually any time. In general, you 
should use a file's name, parent directory ID, and volume reference number to identify a 
file you want to open, delete, or otherwise manipulate. 
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If you need to remember the location of a particular file across subsequent system boots, 
use the Alias Manager to create an alias record describing the file. If the Alias Manager is 
not available, you can save the file's name, its parent directory ID, and the name of the 
volume on which it's located. Although none of these methods is foolproof, they are 
much more reliable than using full pathnames to identify files. 

Nonetheless, it is sometimes useful to display a file's full pathname to the user. For 
example, a backup utility might display a list of full pathnames of files as it copies them 
onto the backup medium. Or, a utility might want to display a dialog box showing the 
full pathname of a file when it needs the user's confirmation to delete the file. No matter 
how unreliable full pathnames may be from a file-specification viewpoint, users 
imderstand them more readily than volume reference numbers or directory IDs. 

Note 

The following technique for constructing the full pathname of a file is 
intended for display purposes only. Applications that depend on any 
particular structure of a full pathname are likely to fail on alternate 
foreign file systems or under future system software versioi\s. ♦ 

Listing 2-5 shows one way to define a function. Get Full Path, that accepts a directory 
ID and a filename as parameters and returns the full pathname of the corresponding file 
(if any). The GetFullPath function calls the low-level function PBGetCatInf o for the 
specified directory to determine the name and directory ID of that directory's parent 
directory. It then performs the same operation on the parent directory's parent, 
continuing imtU it finds a parent directory with ID f sRtDir ID. Under HPS, this is 
always the ID of a volume's root directory. 



Listing 2-5 Constructing the full pattiname of a file 



FUNCTION GetFullPath (DirlD: Longlnt; vRefnuiti: Integer) : Str255; 
VAR 

{parameter block for PBGetCatInf o} 
{a directory name} 
{full pathname being constructed} 



CInf oPBRec; 
Str255; 
Str255; 
OSErr; 



myPB: 
dirName: 
full Path: 
myErr : 
BEGIN 

fullPath := • • ; 
myPB.ioNamePtr := QdirName; 
myPB.ioVRefNum. := vRefNum; 
nr/PB.ioDrParlD := Dirld; 
my PB.ioFDir Index := -1; 



{initialize full pathname} 

.{indicate target vol\ime} 
{initialize parent directory ID} 
{get info about a directory} 



{Get name of each parent directory, up to root directory.} 
REPEAT 

myPB.ioDrDirlD := myPB . ioDrParlD; 
myErr := PBGetCatInf o (@myPB, FALSE); 
IF gHaveAUX THEN 
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BE(?IN 

IF dirName[l] <> V THEN 

dirName : = concat (dirName, ' / ' ) ; 

END 
ELSE 

dirName ;= concat (dirName, ' : ' ) ; 
fullPath := concat (dirName, fullPath) ; 
UNTIL myPB. ioDrDirlD = fsRtDirlD; 

GetFullPath := fullPath; {return full pathname) 

END; 

Note that GetFullPath uses either a slash (/) or a colon (:) to separate names in the hiU 
path, depending on whether A/UX is running or not The GetFullPath function reads 
the value of the global variable gHaveAUX to determine whether A/UX is running; your 
application must initialize this variable (preferably by calling the Gestalt function) 
before it calls GetFullPath. 

The GetFul IPath function defined in Listing 2-5 returns a result of type Str255, 
which limits the full pathname to 255 characters. An actual full pathname, however, 
might exceed 255 characters. A volume name can be up to 27 characters, and each 
directory name can be up to 31 characters. If the average volvime and directory name is 
about 20 characters long, GetFullPath can handle files located only about 12 levels 
deep. If the length of the average directory name is closer to the maximum, 
GetFullPath provides a full pathname for files located only about 8 levels deep. If 
necessary, you can overcome this limitation by rewriting GetFullPath to return a 
handle to the full pathname; the algorithm for ascending the directory hierarchy using 
PBGetCatInf o will still work, however. 

Determining the Amount of Free Space on a Volume 

You can determine how much space is free on a particular volume by calling the 
low-level function PBHGetVInf o. This function returns, in the ioVFrBlk field of the 
parameter block passed to it, the number of free allocation blocks on a volume. It also 
returns, in flie ioVAlBlkSiz field, the number of bytes in the allocation blocks on that 
volume. By multiplying those two values, you can determine how many bytes are free 
on a particular volume. 

There is, however, one complication in this process. The ioVFrBlk field of the 
parameter block is actually an unsigned integer and can contain values from 0 to 65,535. 
However, because Pascal does not support unsigned integers, it interprets the values in 
the IoVFrBlk field as lying in the range -32,768 to 32,767. (Integers are stored as 16-bit 
quantities where the high^rder bit indicates whether the value is true binary or a 
negated value in its two's complement positive form.) If, for example, a volume has 
40,000 allocation blocks free and your application blindly returned the value in the 
ioVFrBlk field, it would erroneously report that the volume had -25,536 allocation 
blocks available. 

You can circimivent this problem by forcing Pascal to interpret the high-order bit as 
part of the number of free blocks. For example, if you install the value returned in the 
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ioVFrBlk field as the low-order word of a long integer, the high-order bit of that 
word is no longer the high-order bit of that long integer and hence is not interpreted 
as a sign indication. The data type Twoint sMakeALong provides a convenient way 
to accomplish this. 

TYPE 

TwoIntsMakeALong = {two integers make a long integer} 

RECORD 

CASE Integer OF 

1: (long: Longlnt) ; 

2: (ints: ARRAY[0..1] OF Integer); 

END; 

Listing 2-6 illustrates how to use this technique to detemunie the amount of free space on 
a volume (specified by its volume reference number). 

Listing 2-6 Determining ttie amount of free space on a volume 



FUNCTION GetVolumeFreeSpace (myVol: Integer): Longlnt; 
VAR 

myHPB: HParamBlockRec ; {parameter block for PBHGetVInfo} 

myErr: OSErr; {result code from PBHGetVInfo} 

nr^^Rec: TwoIntsMakeALong; {easy way to get an unsigned int} 
BEGIN 

WITH myHPB DO 
BEGIN 

ioNamePtr := NIL; 
ioVRefNum := myVol; 
ioVolIndex := 0; 
END; 

myErr := PBHGetVInf o (@myHPB, FALSE); 
IF myErr = noErr THEN 
BEGIN 

myRec.intsfO] := 0; 

myRec.ints[l] := myHPB . ioVFrBlk ; 

GetVolumeFreeSpace :- itryRec.long * rayHPB, ioVAlBlkSiz; 
END 
ELSE 

GetVolumeFreeSpace := 0; 

END; 

If the value passed to GetVolumeFreeSpace is a valid volume reference nimiber, 
then this function reads the number of free allocation blocks on the volume, installs 
that number as the low-order word of a long integer, and performs the necessary 
multiplication to deternune how many bytes are free on the volimie. 
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Note 

You could avoid these complications with imsigned integers by calling 
PBHGetVInf o as illustrated and then passing the value returned in the 
ioVDrvInf o field to the high-level hinction GetVInf o. The technique 
using the TwoIntsMakeALong data type to convert unsigned integers 
to long integers is illustrated here because it is useful when reading the 
fields of many other File Manager data structures from Pascal. For 
example, the vcbFreeBks field of a volume control block contains an 
unsigned integer that you can interpret in this way. ♦ 

Sharing Volumes and Directories 

The File Manager includes several functions that allow you to manipulate share points 
on local voltunes that have file sharing enabled and to obtain a list of user and group 
names and IDs recognized by the local file server. These functions are especiaUy useful 
if you need to implement a dialog box that allows the user to designate a volume or 
directory as a share point or to set the owner, user, and group of a shared folder. 
The PBShare function makes a volume or directory a share point, hence available on the 
network. The PBUnshare function undoes the effects of PBShare: it makes an existing 
share point unavailable on the network. The PBGetUGEntry hinction lets you create a 
list of user and group names and IDs on the local server. 
Before calling any of these functions, you should check whether file sharing is 
enabled on the local machine and, if so, whether the desired local volume is sharable. 
You can determine whether a particular volume is sharable by using the function 
VolIsSharable defined in Listing 2-7. 



Listing 2-7 Determining whether a volume is sharable 

FUNCTION VolIsSharable (vRefNum: Integer): Boolean; 
VAR 

myHPB: HParamBlockRec ; 

mylnfoBuf fer: GetVolParmsInfoBuf f er ; 
myErr: OSErr; 
BEGIN 

WITH myHPB DO 
BEGIN 

ioNamePtr := NIL; 
ioVRefNum := vRefNum; 
ioBuffer := @mylnf oBuf f er ; 
ioReqCount := SizeOf (rnyinf oBuf f er ) ; 
END; 

ittyErr := PBHGetVolParms (©myHPB, FALSE); 
• IF myErr = noErr THEN 

IF BTst (mylnfoBuf fer. vMAtt:rib, bHasPersonalAccessPrivileges) THEN 
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VolIsSharable := TRUE 
ELSE 

VolIsSharable := FALSE 

ELSE 

VolIsSharable := FALSER- 
END ; 



The VolIsSharable function inspects the bHasPersonalAccessPrivileges 
bit returned in the vMAttrib field of the volume attributes buffer it passed to 
PBHGetVol Farms. If this bit is set, local file sharing is enabled on the specified volume. 

You can use the function Sharing I sOn defined in Listing 2-8 to determine whether file 
sharing is enabled on the local machine- 
Listing 2-8 Determining whether file sharing is enabled 



FUNCTION SharinglsOn: Boolean; 
VAR 

myHPB : HParamBlockRec ; 

myErr : OSErr; 
vollndex : Integer ; 
sharing : Boolean ; 
BEGIN 

sharing : = FALSE; {assume file sharing is off) 

vollndex : = 1 ; 

REPEAT 

WITH myHPB DO 
BEGIN 

ioNamePtr := NIL; 
ioVolIndex := vollndex; 
END; 

myErr := PBHGe.tVInf o (@myHPB, FALSE); 
IF myErr = noErr THEN 

sharing := VolIsSharable (myHPB. ioVRefNum) ; 
vollndex := vollndex +1; 
UNTIL (rtiyErr <> noErr) OR sharing; 
SharinglsOn := sharingf; 
END; 

The SharinglsOn function simply calls the VolIsSharable function for each local 
volume (or imtil a sharable volume is found). It uses indexed calls to PBHGetVInf o to 
obtain the volimie reference niunber of each mounted volume. 
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Locking and Unlocking File Ranges 



A me can be opened with shared read/write permission to aUow several users to share 
the data in the fUe. When a user needs to modify a portion of a file that has been opened 
with shared read/write permission, it is usually desirable to make that portion of the hie 
unavaUable to other users whUe the changes are made. You can call the PBLockRange 
function to lock a range of bytes before modifying the file and then PBUnlockRange to 
unlock that range after your changes are safely recorded in the file. 
Locking a range of bytes in a file gives the user exclusive read/write access to that range 
and makes it inaccessible to other users. Other users can neither write nor read the bytes 
in that range until you unlock it. If other users attempt to read data from a portion of a 
file that you have locked, they receive the ELckdErr result code. 
The hmctions PBLockRange and PBUnlockRange are effective only on files that are 
located on volumes that are sharable. U you caU PBLockRange on a file that is not 
located on a remote server volume or that is not currently being shared, no range locking 
occurs Moreover, PBLockRange does not return a result code indicating that no range 
locking has occurred. As a result, you should usuaUy check whether range lockmg will 
be effective on a file before attempting to lock the desired range. 
Usting 2-9 illustrates how you can check to make sure that caUing PBLockRange will 
have the desired effect. 



Listing 2-9 Determining wtiether a file can have ranges locited 



FUNCTION RangesCanBeLocked (fRefNum: Integer): Boolean; 

VAR , , , , 

n^PanuBlk: ParamBldckRec ; (basic parameter block) 

my Err : OSErr ; 

BEGIN 

WITH myParmBlk DO 
BEGIN 

ioRefNum := fRefNum; 

ioRegCount := 1; tlock a single byte) 

ioPosMode := fsFromStart; {at the beginning of the file) 

ioPosOffset := 0; 

END; • 
myErr := PBLockRange (@myParmBlk, FALSE) ; (lock the byte; ignore result) 
myErr := PBLockRange (@myParmBlk, FALSE); {lock the byte again) 



{byte was locked by another user) 



CASE myErr OF 

fLckdErr, ^ . 

afpRangeOverlap, (byte was locked by this user) 

afpNoMoreLocks: t-ax number of locks already used) 
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BEGIN 

RangesCanBeLocked := TRUE; {range locking is supported} 
IF myErr = af pRangeOverlap THEN {unlock the byte we locked) 
myErr := PBUnlockRange (QmyParmBlk, FALSE); 

END; 
OTHERWISE 

RangesCanBeLocked FALSE; {range locking is not supported) 

END; {of CASE) 
END; 

The function RangesCanBeLocked takes a file reference number of an open file as 
a parameter; this is the reference number of the file in which a range of bytes is to 
be locked. The function attempts to locks the first byte in the file.and immediately 
attempts to lock it again. If the second range locking fails with the result code 
af pRangeOverlap, the first call to PBLockRange was successful. If the second call to 
PBLockRange fails with the result code f LckdErr, the byte was already locked by 
another user Similarly, if the second call to PBLockRange fails with the result code 
af pNoMoreLocks, the maximum number of range locks has been reached. In these 
three cases, range locking is supported by the volume containing the specified file. If any 
other result code (including noErr) is returned, range locking is ?iot supported by that 
volume or for some reason the capabilities of the volume cannot be determined. 

Note 

Local file sharing can be started or stopped (via the Sharing Setup 
control panel) while your application is running. For this reason, each 
time you want to lock a range, it's best to check that byte ranges in that 
file can be locked- ♦ 

You can unlock a locked range of bytes by calling PBUnlockRange. Note that the range 
to be unlocked must be the exact same range of bytes that was previously locked using 
PBLockRange. (You can lock and unlock different byte ranges in any order, however.) If 
for some reason you need to unlock a range of bytes and do not know where the range 
started or how long the range is, you must close the fUe to unlock the range. When a file 
is dosed, all locked ranges held by a user are imlocked. 

If you want to append data to a shared file, you can use PBLockRange to lock the range 
df bytes from the file's current log^ical end-of-file to the last possible addressable byte of 
the file. Once you have locked that range, you can write data into it. Listing 2-10 shows 
how to determine the current logical end-of-file and lock the appropriate range. 

Listing 2-1 0 Locking a file range to append data to the file 

FUNCTION LockRangeForAppending (fRefNum: Integer; VAR EOF: Longint) : OSErr; 
VAR 

myParmBlk: ParamBlockRec; {basic parameter block) 

myErr: OSErr; 

my EOF: ..Longint; {current EOF) 
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BEGIN 

myParmBlk. ioCompletion := NIL; 
myParmBlk. ioRefNum -.= ERefNum; 

myErr := PBGetEOF('@inyParmBlk, FALSE); {get the current EOF) 
IF itiyErr <> noErr THEN 
BEGIN 

LockRangeForAppending := myErr; 

Exit(LockRangeForAppencling) ; {trouble reading EOF) 

END; 

myEOF := Longint (myParmBlk. ioMisc) ; {save the current EOF) 
WITH myParmBlk DO 
BEGIN 

ioReqCount := -1; (all addressable bytes} 

ioPosMode := fsFromStart; {start range...} 

ioPosOEfset := myEOF; {---at the current end-of-file} 

END; 

myErr PBLockRange (@myParmBlk, FALSE); {lock the specified range} 
EOF := myEOF; {return current EOF to caller} 

LockRangeForAppending := myErr; 
END; 

The function LockRangeForAppending first determines the current logical end-of-fUe. 
It is irrxportant to get this value immediately before you attempt to lock a range that 
depends on it because another user of the shared file might have changed the end-of-file 
since you last read it. Then LockRangeForAppending locks the range beginnmg at the 
current end-of-file and extending for the maximum number of bytes (specified using the 
special value -1). 

In effect, this technique locks a range where data does not yet exist. Practically speaking, 
locking the entire addressable range of a file prevents another user from appending data 
to the file until you unlock that range. Note that LockRangeForAppending rehims the 
current logical end-of-fQe to the caUer so that the caller can unlock the correct range of 
bytes after appending the data. 

You can also call PBLockRange to lock a range of bytes when you want to truncate a 
file. Locking the end portion of a fUe to be deleted prevents another user from using that 
portion during the truncation. Instead of setting the ioPosOf f set field of the 
parameter block to the logical end-of-file (as in Listing 2-10), simply set it to what wiU be 
the last byte after the file is truncated. SimUarly, you can lock an entire file fork by sethng 
the ioPosOf f set field toO. 



Data Orga nization on Volumes 

This section describes how data is organized on HPS volumes. In general, an application 
that simply manipulates data stored in files does not need to know how that data is 
organized on a volume or on the physical storage medium containing that volume. The 
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organization described in this section is maintained by the File Manager for its own uses. 
Some specialized applications and file-system utilities, however, do need to know 
exactly how file data is stored on a disk. 

WARNING 

This section is provided primarily for informational purposes. The 
organization of data on volumes is subject to change. Before you use this 
information to read or modify the data stored on a volume, be sure to 
check that the drSigWord field in the master directory block (described 
in "Master Directory Blocks" beginning on page 2-59) identifies that 
volume as an HPS volume. A 

Much of the iiiformation describing the files and directories on an HFS volume is read 
into memory when the volume is mounted. (For example, most of the volume's master 
directory block is read into memory as a volume control block.) For a description of how 
that data is organized in memory, see "Data Organization in Memory" beginrung on 
page 2-76. 

The File Manager uses a number of interrelated structures to manage the organization of 
data on disk and in memory. For this reason, it is easy to lose sight of the simple and 
elegant scheme that underiies these structures. As you read through this section and the 
next, you should keep these points in mind: 

■ The File Manager keeps track of which blocks on a disk are allocated to files and 
which are not by storing a volume bitmap on disk and in memory. If a bit in the map is 
set, the corresponding block is allocated to some file; otherwise, the corresponding 
block is free for allocation. 

■ The File Manager always allocates logical disk blocks to a file in groups called 
allocation blocks; an allocation block is simply a group of cor\secutive logical blocks. 
The size of a volume's allocation blocks depends on the capacity of the volume; there 
can be at most 65,535 allocation blocks on a volume. 

■ The File Manager keeps track of the directory hierarchy on a volume by maintairung a 
fUe called the catalog file; the catalog file lists aU the fUes and directories on a volume, 
as well as some of the attributes of those fUes and directories. A catalog file is 
organized as a B*-tree (or "balanced tree") to allow quick and efficient searches 
through a directory hierarchy that is typically quite large. 

■ The File Manager keeps track of which allocation blocks belong to a file by 
maintaining a list of the fUe's extents; an extent is a contiguous range of allocation 
blocks aUocated to some file, which can be represented by a pair of numbers: the start 
of the range and the length of the range. The first ti\ree extents of most files are stored 
in the volume's catalog file. All remaining file extents are stored in the extents overflow 
file, which is also orgaruzed as a B*-tree. 

■ The first three extents of the catalog file and ihe extents overflow file are stored in \he 
master directory block (on disk) and the volume control buffer (in memory); a master 
directory block is always located at a fixed offset firom the beginning of a volume, and 
a volume control block is stored in the VCB queue. 
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Dis k and Volume Organization . 

A disk is a physical medium capable of storing information. Examples of disks include 
3.5-inch floppy disks, SCSI hard disks and CD-ROM discs, and even RAM disks. A SCSI 
disk may be divided into one or more partitions. A partition is simply part of a disk that 
has been allocated to a particular operating system, file system, or device driver. For 
example, you can partition a single SCSI disk into both Macintosh partitions and A/UX 
partitions. The Macintosh partitions are typically used to hold Macintosh volumes. An 
A/UX partition can contain an A/UX file system, but it can also be used as a paging area 
for virtual memory or as a storage area for autorecovery files. 

The information describing the division of a SCSI disk into partitions is contained in the 
disk's partition map, which is always located in the first physical block (512 bytes) on a 
disk. The partition map specifies the first and last physical blocks in each partition, as 
well as additional information about the partition (such as its type). The exact structure 
of a partition map is described in the chapter "SCSI Manager" in Inside Macintosh: Devices. 

Often the first partition on a SCSI disk, following the partition map, is tiie driver 
partition that contains the actual device driver used to communicate with the disk. 
(There is, however, no requirement that the driver partition be the first partition on a 
disk.) Figure 2-4 illustrates a typical organization of partitions on a disk. 
A partition can contain at most one volume. A volume is a single disk partition that 
contains both file data and the file and directory information necessary to maintain the 
appropriate data organization or file system. For example, a volume can contain a 
Macintosh, ProDOS, MS-DOS, or A/UX file system structure. Notice in Figure 2-4 that a 
Macintosh volume occupies only part of the entire physical disk, and that there can be 
multiple partitions (both Macintosh volumes or other types of partitions) on a given disk. 



Note 

The disk organization illustrated in Figure 2-4 does not apply to 
Macintosh 3-5-inch floppy disks. Because each floppy disk is one 
volume, there is no need for a disk partition map. Also, there is no 
device driver partition on a floppy disk. ♦ 

The remainder of this section describes only HFS volumes, that is, Macintosh file 
systems prgariized using the hierarchical file system (HFS) implemented on the 
Macintosh Plus and later models. 

Each HFS volume begins with two boot blocks. The boot blocks on the startup volume 
are read at system startup time and contain booting instructions and other important 
information such as the name of the System file and die Firider. Following the boot 
blocks are two additional structures, the master directory block and the volume bitmap. 

The master directory block contains information about the volume, such as the date and 
time of the volume's creation and the number of files on the volume. The volume bitmap 
contains a record of which blocks in the volume are currently in use. 
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Figure 2-4 Organization of partitions on a disk 
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The largest portion of a volume consists of four types of information or areas: 

■ applications and data files 

■ the catalog file 

■ the extents overflow file 

■ unused space 

The general structure of an HFS volume is illustrated in Figure 2-5. 
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Figure 2-5 Organization of a volume 



Logical 
block 

0 

1 

3 



7 



Contents 



System startup 
information 



Master directory block (MDB) 



Volume bitmap 



Catalog file 



Extents overflow 
file 



Other files and 
free space 



Allocation 
block 



2 



2 



2 



m 

m+1 

m+l 
m+l+1 



2 



n+m+(+k 
P 



m+l+k 



Alternate MDB 



Not used 



All the areas on a voltime are of fixed size and location, except for the catalog file and the 
extents overflow file. These two files can appear anywhere between the volume bitmap 
and the alternate master directory block (MDB). They can appear in arty order and are 
not necessarily contiguous. 

The information on all block-formatted volumes is organized in logical blocks and 
allocation blocks. Logical blocks contain a nimiber of bytes of standard information (512 
bytes on Macintosh-irutialized volumes). Allocation blocks are composed of any integral 
number of logical blocks and are simply a means of grouping logical blocks in more 
convenient parcels. The allocation block size is a volume parameter whose value is set 
when the volmne is irutialized; it carmot be changed urUess the volume is rieinitialized, 

To promote file contiguity and avoid fragmentation, space is allocated to files in groups 
of allocation blocks, or clumps. The clump size is always a multiple of the allocation 
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block size, and it's the minimum number of bytes to allocate each time the Al locat e 
function is called or the physical end-of-file is reached during a write operation. The 
clump size is specified in the catalog information for a file; you can determine the clump 
size using the PBGetCatInf o function. 

The rest of this section describes in detail the structure of the boot blocks, the master 
directory block, and the catalog and extents overflow files. It also describes the general 
structure of a B*-tree, because the catalog and extents overflow files are both organized 
as B*-trees. 

Boot Blocks 



The first two logical blocks on every Macintosh volume are boot blocks. These blocks 
contain system startup information: ii\structions and information necessary to start up 
(or "boot") a Macintosh computer. This iriformation consists of certain configurable 
systeih parameters (such as the capacity of the event queue, the number of open files 
allowed, and so fordi) and is contained in a boot block header. Thef system startup 
information also includes actual machine-language instructions that could be used to 
load and execute the System file. Usually these instructions follow immediately after the 
boot block header. Generally, however, the boot code stored on disk is ignored in favor of 
boot code stored in a resource in the System file. 

The structure of the boot block header can be described by the Pascal BootBlkHdr 
data type. ^ 

▲ WARNING 

The format of the boot block header is subject to change. If your 
application relies on the information presented here, it should check the 
boot block header version number and react gracefully if that number is 
greater than that documented here. A 

Note that there are two boot block header formats. The current format includes two 
fields at the end that are not contained in the older format. These fields allow the 
Operating System to size the System heap relative to the amount of available physical 
RAM. A boot block header that conforms to the older format sets the size of the System 
heap absolutely, using values specified in the header itself. You can determine whether a 
boot block header uses the current or the older format by inspecting a bit in the 
high-order byte of the bbVers ion field, as explained in its field description. 



TYPE BootBlkHdr 

RECORD 
bbID: 
bbEntry : 
bbVersion: 
bbPageFlags: 
bbSysName: 
bbShellName: 
bbDbglName: 



{boot block header} 

Integer; {boot blocks signature) 

Longint; {entry point to boot code) 

Integer; {boot blocks version number) 

Integer; {used internally) 

Strl5; {System filename) 

StrlS; {Finder filename) 

StrlS; {debugger filename) 



I 
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bbDbg2Name : 


StrlS; 


(debugger filename} 




bbScreenName : 


Strl5; 


(name of startup screen) 


bbHelloName: 


StrlS; 


{name of startup program) 


bbScrapName : 


Strl5; 


{name of system scrap 


file) 


bbCntFCBs: 


Integer; 


{number of FCBs to allocate) 


bbCntEvts: 


Integer; 


{number of event queue elements) 


bbl28KSHeap: 


Longint ; 


(system heap size on 


128K Mac) 


bb256KSHeap: 


Longint; 


(used internally) 




bbSysHeapSize: 


Longint; 


(system heap size on 


all machines) 


filler: 


Integer; 


(reserved) 




bbSysHeapExtra : 


Longint ; 


{additional system heap space) 


bbSysHeapFract : 


Longint ; 


(fraction of RAM for 


system heap) 



END; 

Field descriptions 

bbID 

bbEntry 



bbVersion 



A signahire word. For HFS volumes, this field always contains the 
value $4C4B. 

The entry point to the boot code stored in the boot blocks. This 
field contains machine-language instructions that h*anslate to 
BRA . S * + S 9 0 (or BRA . S * + $ 8 8, if the older block header format 
is used), which jumps to the main boot code following the boot 
block header. This field is ignored, however, if bit 6 is clear in the 
high-order byte of the bbVersion field or if the low-order byte in 
that field contains $D. 

A flag byte and boot block version number. The high-order byte of 
this field is a flag byte whose bits have the following mearungs: 

Bit Meaning 

0-4 Reserved; must be 0 

5 Set if relative system heap sizing is to be used 

6 Set if the boot code in boot blocks is to be executed 

7 Set if new boot block header format is used 

If bit 7 is clear, then bits 5 and 6 are ignored and the version number 
is found in the low-order byte of this field. If that byte conmins a 
value that is l6ss than $15, the Operating System ignores any valu^ 
in the bbl2 SKSHeap and bb256KSHeap^^fields and configures the 
System heap to the default value contained in the bbSysHeapSize 
field. If that byte contair\s a value that is greater than or equal to 
$15, the Operating System sets the System heap to the value in 
bbSysHeapSize. In addition, the Operating System executes 
the boot code in the bbEntry field only if the low-order byte 
contains $D. 

if bit 7 is set, the Operating System inspects bit 6 to determine 
whether to execute the boot code contained In the bbEntry field 
and bit 5 to determine whether to use relative System heap sizing. If 
bit 5 is dear, the Operating System sets the System heap to the value 
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bbPageFlags 
bbSysName 
bbShellName 
bbDbglName 

bbDbg2Name 

bbScreenName 

bbHelloName 
bbScrapName 
bbCntFCBs 



in bbSysHeapSize. If bit 5 is set, the System heap is extended by 
the value in bbSysHeapExtra plus the fraction of available RAM 
specified in bbSysHeapFract. 
Used internally. 
The name of the System file. 

The name of the shell file. Usually, the system shell is the Finder. 
The name of the first debugger installed during the boot process. 
Typically this is Macsbug. 

The name of the second debugger installed during the boot process. 
Typically this is Disassembler. 

The name of the file containing the startup screen. Usually this is 
StartUpScreen. 

The name of the startup program. Usually this is Finder. 
The name of the system scrap file. Usually this is Clipboard. 
The number of file conhrol blocks (FCBs) to put in the FCB buffer. In 
system software version 7.0 and later, this field specifies only the 
initial number of FCBs in the FCB buffer, because the Operating 
System can usually resize the FCB buffer if necessary. See 'Tile 
Control Blocks" on page 2-81 for details on the FCB buffer. 
The number of event queue elements to allocate. This number 
determines the maximum number of events that the Event Manager 
can store at any one time. Usually this field contains the value 20. 
The size of the System heap on a Macintosh computer having 
128 KB of RAM. 
Reserved. 

The size of the System heap on a Macintosh computer having 
512 KB or more of RAM. This field nught be ignored, as explained 
in the description of the bbVersion field. 
Reserved. 

The minimum amoimt of additional System heap space required. If 
bit 5 of the high-order word of the bbVer s ion field is set, this 
value is added to bbSysHeapSize. 
bbSy sHeapFract: The fraction of RAM available to be used for the System heap. If 
bit 5 of the high-order word of the bbVer s ion field is set, this 
fraction of available RAM is added to bbSysHeapSize. 



bbCntEvts 

bbl28KSHeap 

bb256KSHeap 
bbSysHeapSize 

filler 

bbSy sHeapExt ra 



I 



3 
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Master Directory Blocks 

A master directory block (MDB) — also sometimes knovm as a volume information 
block (VIB)— <:ontains information about the rest of the volume. This information is 
written into the MDB when the volume is initialized. Thereafter, whenever the volume is 
mounted, the File Manager reads the information in the MDB and copies some of that 
information into a volume control block (VCB). A VCB is a private data structure 
maintained in memory by the File Manager (in the VCB queue). The sbruchire of a VCB 
is described in "Volume Control Blocks/' later in this chapter. 
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Note in Figure 2-5 (page 2-56) that a copy of the MDB is located in the next-to-last block 
in the volume. This copy is updated only when the extents overflow file or the catalog 
file grows larger. This alternate MBD is intended for use solely by disk utilities. 

The MDB data type defines a master directory block record. 

TYPE MDB = {master directory block} 

RECORD 



drSigWord: 


Integer; 


{volume signature} 


drCrDate: ^ 


Longint ; 


(date and time of volume creation} 


drLsMod : 


Longint ; 


{date and time of last modification} 


drAtrb: 


Integer; 


{volume attributes} 


drMmFls: 


Integer; 


{number of files in root directory} 


drVBMSt : 


Integer; 


{first block of volume bitmap} 


drAllocPtr : 


Integer; 


{start of next allocation search} 


drNitvAlBlks: 


Integer; 


{number of allocation blocks in volume} 


drAlBlkSiz: 


Longint ; 


{size (in bytes) of allocation blocks} 


drClpSiz: 


Longint ; 


{default clump size} 


drAlBlSt : 


Integer; 


{first allocation block in volume) 


jdrNxtCNID: 


Longint ; 


{next unused catalog node ID} 


drFreeBks : 


Integer; 


{number of unused allocation blocks} 


drVN: 


String [27] ; 


{volume name) 


drVolBkUp: 


Longint; 


{date and time of last backup) 


drVSeqNum : 


Integer; 


{volume backup sequence number} 


drWrCnt : 


Longint ; 


{volume write count) 


drXTClpSiz: 


Longint ; 


{clump size for extents overflow file} 


drCTClpSiz: 


Longint; 


{clump size for catalog file) 


drNmRtDirs: 


Integer; 


{number of directories in root directory) 


drFilCnt : 


Longint ; 


{number of files in volume) 


drDirCnt : 


Longint; 


{number of directories in volume) 


drFndrlnfo; 


ARRAY [1. .8] 


OF Longint; 






{information used by the Finder) 


drVCSize: 


Integer; 


{size (in blocks) of volume cache) 


drVBMCSize: 


Integer; 


{size (in blocks) of volume bitmap cache) 


drCtlCSize: 


Integer; 


{size (in blocks) of common volume cache) 


drXTFlSize: 


Longint; 


{size of extents overflow file) 


drXTExtRec: 


ExtDataRec; {extent record for extents overflow file} 


drCTFLSize: 


Longint ; 


{size of catalog file) 


drCTExtRec: 


ExtDataRec; {extent record for catalog file) 



END; 



Field descriptions 

dr S igWord The volume signature. For HPS volumes, this field contains $4244; 

for the obsolete flat MFS volumes, this field contains $D2D7. 
drCrDate The date and time of volume creation (initialization). 
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drLsMod 
drAtrb 



drNmFls 
drVBMSt 

drAllocPtr 

drNmAlBlks 

drAlBlkSiz 

drClpSiz 

drAiaiSt 

drNxtCNID 

drFreeSks 

drVN 



drVolBkUp 
drVSeqNum 
drWrCnt 

drXTClpSize 

drCTClpSize 

drNmRtDirs 

drFilCnt 

drDirCnt 

drFndrlnfo 



drVCSize 
drVBMCSize 

drCtlCSize 



The date and time the volume was last modified. This is not 
necessarily when the volume was last flushed. 
Volume attributes. Currently the following bits are defined: 
Bit Meaning 

7 Set if the volume is locked by hardware 

8 Set if the volume was successfully unmounted 

9 Set if the volume has had its bad blocks spared 
15 Set if the volume is locked by software 

The number of files in the root directory. 

The first block of the volume bitmap. This field always contains 3 in 
the current implementation. 

The number of the allocation block at which the next allocation 
search will begin. Used internally. 

The number of allocation blocks in the volume. Because the value in 
this field is an integer, a volume can contain at most 65,535 
allocation blocks. 

The allocation block size (in bytes). This value must always be a 
multiple of 512 bytes. 
The default clump size. 

The location of the first allocation block, in the volume. 

The next unused catalog node ID (directory ID or file ID). 

The number of unused allocation blocks on the volume. 

The volume name. This field consists of a length byte followed 

by 27 bytes. Note that the volume name can occupy at most 

27 characters; this is an exception to the normal file and directory 

name limit of 31 characters. 

The date and time of the last volume backup. 

Volume backup sequence number. Used internally. 

The volume write count (that is, the number of times the volume 

has been written to). 

The dump size for the extents overflow file. 

The cliunp size for the catalog file. 

TTie niimber of directories in the root directory. 

The number of files on the volume. 

The number of directories on the volvune. 

Information used by the Finder. See the chapter "Finder Interface" 
in Inside Macintosh: Macintosh Toolbox Essentials for details on 
Finder ir\formation. 

The size (in allocation blocks) of the volume cache. Used internally. 
The size (in allocation blocks) of the volume bitmap cache. 
Used internally. 

The size (in allocation blocks) of the common volimie cache. 
Used internally. 
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drXTFlSize 
drXTExtRec 

drCTFlSize 
drCTExtRec 



The size (in allocation blocks) of the extents overflow file. 

First extent record for the extents overflow file. An extent record ^ 

an array of three extents. See "Extents Overflow Files on page 2-74 

for a description of extents and extent records. 

The size (in allocation blocks) of the catalog file. 

First extent record for the catalog file. 



Note , ,ju 

The values in the drNmAlBlks and drFreeBks fields should be 
interpreted as unsigned integers (that is, they can range fix)m 0 to 65,535, 
not fi-om -32,768 to 32,767). Pascal does not support unsigned data 
types, and so you need to use the technique illustrated in"Determmmg 
tixe Amount of Free Space on a Volume" on page 2-46 to read the values 
in these fields correctiy. ♦ 



Vol ume Bitmaps ^ 

^Vile Manager uses a volume bitmap to keep track of whether each block in a volume 
^iLntly allLted to some file or not. Tl.e bitmap contains one b^^ 
block in the volume. If a bit is set, the corresponding allocation block is currently m use 
by some file. If a bit is clear, the corresponding allocation block is not currently m use by 
any file and is available for allocation. 

Note , . 

The volume bitmap indicates which blocks on a volume are currently m 
use but it does not indicate which files occupy which blocks. The PUe 
Manager maintains file-mapping information in two locations: in each 
file's catalog entry and in the extents overflow file. ♦ 

The size of the volume bitmap depends on the number of allocatton blocks in the 
volume, which in turn depends both on the number of physical blocks m the volume 
and on the size of the volume's allocation blocks (the number of physical blocks per 
aIlocationblock).Forexample,afloppy disk that canhold 800 KBofdataand^^^^^ 
aUocation block size of one physical block has a volume bitmap s^ze o 1600 bits 200 
bytes). A volume containing 32 MB of data and having an allocation block size ^f one 
physical block has a voluihe bitmap size of 65,536 bits (8192 bytes). However, the 

L volmne bitmap is rounded up, if necessary, so that the volume bitmap occupies an 
integral number off physical blocks. 

Because die drNmAlBlks field in the MDB occupies only 2 bytes, the File Manager can 
address at most 65,535 allocation blocks. Thus, the volume bitmap is never larger than 
8192 bytes (or 16 physical blocks). For volumes containing more than 32 MB of ^pac^' 
allocation block size must be increased. For example, a volume containing 40 MB of 
spacemusthaveanaUocationblocksizethatisatleast2physicalblocks;avGlume 

containing 80 MB of space must have an aUocation block size that is at least 3 physical 

blocks; and so forth. 
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B*-Trees 



The File Manager maintains information about a volume's directory hierarchy and file 
block mapping in two files that are organized as B*-trees to allow quick and efficient 
retrieval of that information. In a B*-tree, all the information that needs to be stored is 
intelligently classified and sorted into objects called nodes. Fig;ure 2-6 illustrates the 
general structure of a B*-tree file. 



Figure 2-6 The structure of a B'-tree file 
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Note that eadi B*-tree file used by the File Manager makes use of the data fork only; the 
resource fork of a B*-tree file is unused. The length of a B*-tree file varies according to the 
number of nodes it contains. 

A node in turn contains records, which can be used for a variety of purposes. Some 
records contain the actual data that is to be retrieved and possibly updated; these records 
occupy nodes called leaf nodes. Other records contain information about the structure of 
the B*-tree. The File Manager uses these records to find the information it needs quickly. 
There are three types of these Tjookkeeping" nodes: header nodes, index nodes, arid 
map nodes. 
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Nodes 



ABMreefileconsists entirely of objects called nodes,each of wMchis512 
Figure 2-7 illustrates the structure of a node. 

Each node has the same general struch«:e and consists of three main P^^^^^^^^^^ 
descriptor that starts at the beginning of the node, a group of record offsets that starts 
at the end of the node, and a group of records. 

The node descriptor contains information about the node, as well as ^^^^ 
bayard links to other nodes. You can use the NodeDescr iptor data type to display 
the structure of a r\ode descriptor. 



TYPE NodeDescriptor - 
RECORD 

ndFLink: Longint; 

ndBLink: Longint; 

ndType: SignedByte; 

ndNHeight : SignedByte; 

ndNRecs: Integer; 

ndResv2: Integer; 
END; 



(node descriptor} 

{forward link} 
(backward link} 
(node type} 
(node level} 

(number of records in node} 
{reserved} 



Figure 2-7 The structure of a node 
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Field descriptions 

ndFLink A link to the next node of this type. If this node is the last node, this 

field contains NIL. 

ndBLink A link to the previous node of this type. If this node is the first node, 

this field contains NIL. 

ndType The type of this node. Currently four types of nodes are recognized, 

defined by the constants listed in this section. 

ndNHeight The level or "depth" of this node in the B*-tree hierarchy. The 

top-level node (a header node, described in "Header Nodes" on 
page 2-67) always has a level of 0; all other nodes have a level that is 
one greater than their parent node. Currently, the maximum depth 
of a node is 8. 

ndNRec s The number of records contained in this node. 

ndResv2 Reserved. This field should always be 0. 

A node descriptor is always $0E bytes in length, and so the records contained in the 
node always begin at offset $0E from the beginning of the node. The size of a record can 
vary, depending on its type and on the amount of information it contains; as a result, the 
File Manager accesses a record by storing the offset from the beginning of the node to 
that record in the list of offsets found at the end of the node. Each offset occupies a word, 
and (as you might have guessed) the last word in a node always contains the value $0E, 
pointing to the first record in the node. The offsets to subsequent records are stored in 
order starting from the end of the node, as illustrated in Figure 2-7. 

Note that there is always one more offset than the number of records contained in a 
node; this is an offset to the beginning of any imused space in the node. If there is no free 
space in the node, then that offset contains its own byte offset within the node. 

The ndType field of the node descriptor indicates the type of a node. In essence, the type 
of a node indicates what kinds of records it contains and hence what its function in the 
B*-tree hierarchy is. The File Manager maintains four kinds of nodes in a B*-tree, 
indicated by constants: 



CONST 

ndlndxNode 
ndHdrNode 
ndMapNode 
ndLeafNode 



$00 
$01 
$02 
$FF 



{node types) 
{index node) 
{header node} 
{map node) 
.{leaf node) 



These node types are described in the four sections immediately after the next one. 
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Node Records 

A record in a B*-tree node contains either data or a pointer to some othei 
tree. Figure 2-8 shows the general structure of a record in a leaf or index 



Figure 2-8 Stmcture of a B*-tree node record 
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Note 

The three records in a B»-tree header node do not have the structure 

depicted in Figure 2-8. They consist solely of data, as descnbed in the 

next section, "Header Nodes." Similarly, the single record m a map node 

consists solely of data; see "Map Nodes" on page 2-69 for detads. ♦ 

Each record contains a search key, which the FUe Manager uses to search through the 

B*-tree to locate the information it needs. TTie key can contain any mformation at all that 

is deemed usehil in finding the data contained in the leaf nodes. In a catalog fil^ which 

maintains information about the hierarchy of files and directories on a volume, the 

search key is a combination of the file or directory name and the parent directory ID of 

that file or directory. In an extents overflow file, which maintains f °" 

extra extents belonging to a file, the search key is a combination of that fUe s type, its hie 

ID, and the index of the first allocation block in the extent. 

In a B*-tree, the records in each node are always grouped so that their keys are in 

ascending order. Moreover, the nodes on any given level are linked (through the 

ndFLink and ndBLink fields of their node descriptors) in such a way as to preserve the 

ascending order of record keys throughout that level. This is the essential ordermg 

prindple that aUows the File Manager to search quickly through a tree To iBusto^^ 

ordering scheme. Figure 2-9 shows a sample B*-tree containing hypothetical search keys 

(in this case, the keys are simply integers). 

When the FOe Manager needs to find a data record, it begins searching at the root node 
(which is an index node, unless the tree has only one level), moving from one record to 
the next until it finds the record with the highest key that is less than or equal to the 
search key Hie pointer of that record leads to another node, one level down m the tree. 
This process continues until the File Manager reaches a leaf node; then the records of 
that leaf node are examined until the desired key is found. At that point, the desired data 
has also been found. 
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Figure 2-9 A sample B*-lree 




There is of course no guarantee that a record having the desired key will always be 
found in a search through a B*-tree. In this case, the search stops when a key larger 
than the search key is reached. (This is most likely to happen in a search through the 
catalog file.) 

Header Nodes 

The first node (that is, node 0) in every B*-tree file is a header node, which contains 
essential information about the entire B*-tree file. The File Manager stores the location of 
the header node of the catalog file in the first 2 bytes of the drCTExtRec field of the 
MDB; the value in those 2 bytes indicates the allocation block number on which the 
catalog file (and hence the header node) begiris. Similarly, the File Manager stores the 
location of the header node of the extents overflow file in the first 2 bytes of the 
drXTExtRec field of the MDB. 

Note 

When a volume is mounted, the File Manager reads the header node 
and copies some of the information it conitains into a B*-tree control 
block in memory. See "B*-Tree Control Blocks" on page 2-83 for a 
description of this control block. ♦ 

A header node contains three records, the second of which occupies 128 bytes and is 
reserved for use by the File Manager. TTie other two records are called the B*-tree header 
record and the B*-tree map record; they occupy the first and third record positions, 
respectively. Hence, a header node has the structure illustrated in Figure 2-10. 
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Figure 2-1 0 Header node structure 
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Note . , 

The three records contained in the header node do not contain keys. ♦ 

The map record is a bitmap' that indicates which nodes in the BMree fUe are i^ed and 

bitmap- if a bit in the map record is set, then the correspondmg node m he B -tree hie is 
be^^^^^^ This bitmap occupies 256 bytes and can therefore encode mformahon about 
imZes at most. If more nodes are needed to contain all the data that is to be stored 
in the B-tree, the File Manager uses a map node tostore additional mappmg mforma- 
^rSeethe^extsection/ipN^^^^^^ 

Ihe BMree header record/a data structure of type BTHdrRec, contaii^ information 
about the beginning of the tree, as weH as the size of the tree.; 



TYPE BTHdrRec 

RECORD 

bthDepth: 
bthRoot : 
bthNRecs : 
bthFNode : 
bthLNode : 
bthNodeSize: 
bthKeyLen: 



Integer; 
Longint ; 
Longint ; 
Longint ; 
Longint ; 
Integers- 
Integer; 



{B*-tree header) 

{current depth of tree) 

{number of root node) 

{number of leaf records in tree) 

{number of first leaf node) 

{number of last leaf node) 

{size of a node) 

{maximum length of a key} 
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bthNNodes: Longint; {total number of nodes in tree) 

bthFree: Longint; {number of free nodes) 

bthResv: ARRAY[1..76) OF SignedByte; (reserved) 

END; 

Field descriptions 

bthDepth The current depth of the B*-tree. 

bthRoot The node number of the root node. The root node is the start of the 

B*-tree structure; usually the root node is first index node, but it 
might be a leaf node if there are no index nodes. 

bthNRecs The number of data records (records contained in leaf nodes). 

bthFNode The node number of the first leaf node. 

bthLNode The node number of the last leaf node. 

bthNodeSi ze The size (in bytes) of a node. Currently, this is always 512. 

bthKeyLen The maximum length of the key records in each node. 

bthNNodes The total number of nodes in the B*-tree. 

bthFree The total number of free nodes in the B*-tree. 

bthResv Reserved. 

Map Nodes 

As indicated in the previous section, the File Manager maintains a bitmap of the tree 
nodes in the map record of the B*-tree header node. If a B*-tree file contains more than 
2048 nodes (enough for about 8000 files), the File Manager uses a map node to store 
additional node-mapping information. It stores the node number of the new map node 
in the ndFLin)c field of the node descriptor of the header node. 

A map node consists of a node descriptor and a single map record. The map record is a 
continuation of the map record contained in the header node and occupies 494 bytes 
(512 bytes in the node, less 14 bytes for the node descriptor and 2 bytes for each of the 
two record offsets at the end of the node). A map node can therefore contain mapping 
information for an additional 3952 nodes. 

If a B*-tree contains more than 6000 nodes (tfiat is, 2048 + 3952, enough for about 25,000 
files), the File Manager uses a second map node, the node number of which is stored in 
the ndFLink field of the node descriptot of the first map node. If more map nodes are 
reqiiifed, each additional map node is similarly linked to the previous one. 

index Nodes . ^ 

An index node contains records that point to other nodes in the B*-tree hierarchy. The 
File Manager uses index nodes to navigate the tree structure quickly when it wants to 
find some data (which is always stored in leaf nodes). Index nodes speed a tree search by 
dividing the tree into smaller pieces, as illustrated in Figure 2-9 {page 2-67). 

The rfecbirds stored in ah index riode arfe called pointer records. A pointer record consists 
of a key fpjlowed by the node number of the corresponding node. The structure of the 
key varies according to the type of B*-tree file that contains the index node. For a catalog 
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file the search key is a combinaHon of the file or directory iiame and the parent directory 
ID 'of that file or directory. In an extents overflow file, the seard^key is a --^mahon of 
that file's type, its file ID, and the index of the first allocation block m the extent See the 
l^oli ''SLlog Fde K^s" on page 2-71 and "Extents Overflow Files" on page 2-74 for 
more details on the struchire of index node search keys. 

The immediate descendants of an index node are caUed the children of the index node. 
Ai. index node can have from 1 to 15 children, depending on the size of the pomter 
records that the index node contains. TypicaUy the File Manager selects one of the node s 
children and continues the search at that node; the File Manager may stop the seardv, 
however, if the index node does not contain a pointer record with the appiopnate key. 
The first index node in a B*-tree is called the root node. Recall that the B*-tree 
header node contains the node number of the root node in the bthRoot field of 
the header record. 



Leaf Nodes 



•me bottom level of a B»-tree structure is occupied exclusively by leaf nodes, which 
contain data records (not pointer records). The struchire of the leaf node data records 
varies according to the type of B*-tree under consideration. In an extents overflow file, 
the leaf node data records consist of a key and an extent record. In a catalog file 

(described in the next secHon), the leaf node data records can be any one of four kmds 

of records. 



Catalog Files 

The File Manager uses a file called the catalog file to maintain information ^bout the 
hierandty of files and directories on a volume. A catalog file is organized as a B -tree hie 
and hence consists of a header node, index nodes, leaf nodes, and (i ne^e^sary) map 
nodes. The allocation block number of the first file extent of the catalog file (and hence of 
the file's header node) is stored in the MDB; when the volume is mounted, that 
irxfonnation is copied into that volume's volmne control block. From the header node, 
the FUe Manager can obtain the node number of the catalog file's root node; from the 
root node, the File Manager can find the entire catalog file. 

Each node of the catalog file is assigned a uni^iue catalog node ID (CNID). For directo- 
ries the CNID is the directory ID; for files, it's the file ID. For any given file or d«^tory, 
the parent ID is the CNID of the parent directory. The first 16 CNIDs are reserved for use 
by Apple Computer, Inc., and include the foUowing standard assignments: 

CNID Assignment 

1 Parent ID of the root directory 

2 Directory ID of the root directory 

3 File number of the extents file 

4 File number of the catalog file 

5 File number of the bad allocation block file 
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You need to know only two things about a catalog file in addition to the information 
given earlier in this chapter in "B*-Trees": 

■ the format of the catalog key used in index and leaf nodes 

■ the format of the leaf node data records 

These formats are described in the following two sections. 



Catalog File Keys 



The key that the File Manager uses to navigate the catalog file is simple: for a given file 
or directory, the key consists principally of the name of that file or directory and its 
parent directory ID. Wiih the exception of a volume reference number (which is not 
needed here), this mirrors the standard way to specify a file or directory with the 
high-level HFS routines. You can describe a catalog file key using a record of the 
CatKeyRec data type. 



{catalog key record} 

{key length} 
{reserved} 

{parent directory ID} 
{catalog node name} 



TYPE CatKeyRec 
RECORD 

ckrKeyLen : SignedBy te ; 

ckrResrvl : SignedBy te ; 

ckrPar ID : Longint ; 

ckrCName : S tr3 1 ; 

END; 

Field descriptions 

CkrKeyLen The length (in bytes) of the rest of the key. The value in this field 

does not include the byte occupied by the field itself. If this field 
contains 0, the key indicates a deleted record, 

ckrResrvl Reserved. 

ckrParlD The catalog node ID of the parent directory. 

ckrCName The name of the file or directory whose catalog entry is to be found. 

This field is padded with null diaracters if necessary to have the 
next record data or pointer begin on a word boimdary. 

You should pay special attention to the fact that the catalog key differs slightly 
depending on whether it occurs in a record in an index node or a leaf node; If the key 
occurs in a ppiriter record flience in an index liode), the ckrCName field always occupies 
a full 32 bytes and the ckrKeyLen field always contains the value $25. 

If, however, the catalog file key occurs in a data record (hencie in a leeif node), then the 
ckrCName field varies in length; it occupies only the number of bytes required to hold 
the file or directory name, suitably padded so that the data following it begins on a word 
boundary. In that case, the ckrKeyLen field varies as well and may contain values from 
$7 to $25. 
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Catalog File Data Records 



A catalog file leaf node can contain four different types of records: 

. Directory records. A directory record contains information about a single directory. 

■ FUe records. A file record contains information about a single file. 

. Directory thread records. A directory thread record provides a » bf^^" ^ 

diiectoS' and its parent directory. It allows the File Manager to find the name and 

directory ID of the parer>t of a given directory. 
. Filethreadrecords.Afilethreadrecordprovidesalinkbetweenafileanditspare^^^ 

directo^. It aUows the FUe Manager to find the name and directory ID of the parent of 

a given file. 

Each record is defined by a variant of the CatDataType data type. 



TYPE CatDataType 



TYPE CatDataRec 

RECORD 

cdrType : 
cdrResrv2 : 

CASE CatDataType 

cdrDirRec: 
(dirFlags: 
dirVal: 
dirDirlD: 
dirCrDat : 
dirMdDat: 
dirBkDat : 
dirUsrInf o: 
dirFndrlnfo: 
dirResrv: 

cdrFilRec: 
(filFlags: 
filTyp: 
f ilUsrWds: 
f ilFlNum: 
filStBlk: 
f ilLgLen: 
f ilPyLen: 
f ilRStBlk: 
f ilRLgLen: 
f ilRPyLen: 
filCrDat: 



(CdrDirRec, cdrFilRec, cdrThdRec, 
cdrFThdRec) ; 



SignedByte; 
SignedByte; 
OF 

Integers- 
Integer; 
Longint ; 
Longint ; 
Long In t ; 
Longint ; 
DInfo; 
DXInfo; 
ARRAY[1. .41 



SignedByte; 
SignedByte; 
Finfo; 
Longint; 
Integer; 

Longint ; 

Longint; 

Integer; 

Longint ; 

Longint ; 

Longint ; 



(catalog data records) 

{record type) 
{reserved} 

{directory record} 
(directory flags} 
{directory valence} 
(directory ID} 
(date and time of creation} 
{date and time of last modification} 
{date and time of last backup} 
{Finder information) 
(additional Finder information} 
OF Longint ) ; 
{reserved} 
{file record} 
{file flags} . 
{file type} 
(Finder information) 
(file ID} 

{first alloc, blk. of data fork} 
(logical EOF of data fork} 
(physical EOF of data fork) 
(first alloc, blk. of resource fork} 
(logical EOF of resource fork) 
(physical EOF of resource fork} 
{date and time of creation) 
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filMdDat : 
f ilBkDat : 
f ilFndrlnfo: 
f ilClpSize: 
f ilExtRec: 
f ilRExtRec: 
f ilResrv: 
cdrThdRec :. 
(thdResrv: 

thdParlD: 
thdCName: 
cdrFThdRec : 
{ EthdResrv: 

fthdParlD: 
f thdCName: 
END; 



Longint; 

Longint ; 

FXInfo; 

Integer; 

ExtDataRec; 

ExtDataRec; 

Longint ) ; 

ARRAY [ 1 . . 2 ] 

Longint; 
Str31) ; 

ARRAY [1. .2) 

Longint ; 
Str31) ; 



(date and time of last modification} 

{date and time of last backup} 

{additional Finder information) 

(file clump size} 

(first data fork extent record) 

(first resource fork extent record) 

(reserved) 

(directory thread record) 

OF Longint; 

(reserved) 

(parent ID for this directory} 
(name of this directory} 
(file thread record} 
OF Longint; 
(reserved) 

(parent ID for this file) 
{name of this file) 



The first two fields of a catalog data record are common to all four variants. Each variant 
also iiicludes its own unique fields. 

Field descriptions common to all variants 



cdrType 



The type of catalog data record. This field can contain one of four 
values: 



cdrResrv2 



Value 
1 

2 
3 
4 

Reserved. 



Meaning 

Directory record 
File record 

Directory thread record 
File thread record 



Field descriptions 

ditlFlags 

diirVal 

dirDirlD 

dirCrDat 

dirMdDat 

dirBkDat 

dirUsrInf o 

dirFndrlnfo 

dirResrv 



for the cdrDirRec variant 
Directory flajgs. 

The directory valence (the ntunber of files in this directbry). 
The directory ID. 

The date and time this directory was created. 
The date iand time this directory was last modified. 
The date and time this directory was last backed up. 
Information used by the Finder. 
Additional iivfonriation used by the Finder. 
Reserved. 
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Field descriptions 

f ilFlags 



for the cdrFilRec variant 

File flags. This is interpreted as a bitmap; currently the following 
bits are defined: 
Bit Meaning 

0 If set, file is locked and cannot be written to. 

1 If set a file thread record exists for this file. 
7 If set, the file record is used. 



f ilTyp 
f ilUsrWds 
filFlNum 
filStBlk 
f ilLgLen 
f ilPyLen 
f ilRStBlk 
f ilRLgLen 
f ilRPyLen 
filCrDat 
f ilMdDat 
f ilBkDat 
filFndrlnfo 
f ilClpSize 
f ilExtRec 
f ilRExtRec 
f ilResrv 



The file type. This field should always contain 0. 
The file's Finder information. 
The file ID. 

The first allocation block of the data fork. 

The logical EOF of the data fork. 

The physical EOF of the data fork. 

The first allocation block of the resource fork 

The logical EOF of the resource fork. 

The physical EOF of the resource fork. 

The date and time this file was created. 

The date and time this file was last modified. 

The date and time this fUe was last backed up. 

Additional information used by the Finder. 

The file dump size. 

The first extent record of the file's data fork. 
The first extent record of the file's resource fork. 
Reserved. 



Raid descriptions for the cdrThdRec variant 
thdResrv Reserved. 

thdParlD The directory ID of the parent of the associated directory. 

thdCName The name of this directory. 

Field descriptions f or the cdrFThdRec variant 
fthdResrv Reserved. 

f thdParlD The directory ID of the parent of the associated file. 

f thdCName The name of this file. 

As you can see, a file thread record is exactly the same as a directory thread record 
except that the associated object is a file, not a directory. 

Extents Overflow Files 



The FQe Manager keeps track of which aUocation blocks belong to a file by mamtammg a 
list of contiguous disk segments that belong to that file, in the appropriate order. When 
the Ust of disk segments gets too large, some of those segments (or extents) are stored on 
disk in a file called the extents overflow file. 
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The structure of an extents overflow file is relatively simple compared to that of a catalog 
file. The function of the extents overflow flle is to store those file extents that are not 
contained in the MDB or VCB (in the case of the catalog and extents overflow files 
themselves) or in an FCB (in the case of all other files). Because the first three file extents 
are always maintained in memory (in a VCB or an FCB), the File Manager needs to read 
the extents overflow file only to retrieve any file extents beyond the first three; if a file 
has at most three extents, the File Manager never needs to read the disk to find the 
locations of the file's blocks. (This is one good reason to promote file block contiguity.) 

An extent is a contiguous range of allocation blocks that have beeri allocated to some file. 
You can represent the structure of an extent using an extent descriptor, defined by the 
ExtDescriptor data type. 

TYPE ExtDescriptor = {extent descriptor) 

RECORD 

xdrStABN: Integer; {first allocation block) 

xdrNuiuABlks: Integer; {number of allocation blocks) 

END; 

An extent descriptor record corisists of the first allocation block of the extent, followed 
by the number of allocation blocks in that extent. The File Manager prefers to access 
extent descriptors in groups of three; to do so, it uses the extent data record, defined by 
the ExtDataRec data type. 

TYPE , 

ExtDataRec: ARRAYtl..3] OF ExtDescriptor ;{ extent data record) 

Recall that the drCTExtRec and drXTExtRec fields of the MDB are of type 
ExtDataRec (see "Master Directory Blocks," earlier in this chapter), as is the 
f cbExtRec field of an FCB (see "File Control Blocks" begirming on page 2-81). Also, 
the records in the leaf nodes of the extents overflow file are extent data records. For 
this reason, the extents overflow file is much simpler than the catalog file: the data in 
a leaf node of an extents overflow file always consists of a single kind of record, 
instead of the four kinds of records found in a catalog file. 

The other main difference between a catalog B*-tree and an extents overflow B*-tree 
concerns the format of the key. You can describe an extent record key with the 
ExtKeyRec data type. 



TYPE ExtKeyRec 
RECORD 

xkrKeyLen: SignedByte; 
xkrFkType: SignedByte; 
xkrFNum: Longint; 
xkrFABN: Integer; 
END; 



{extent key record) 

{key length) 
{fork type) 
{file number) 

{starting file allocation block) 
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The length (in bytes) of the rest of the key. In the current 
implementation, this field always contains the value 7, 
The type of fQe fork. This field contains $00 if the file is a data fork 
and $FF if the file is a resource fork. 
The file ID of the file. 

The starting file allocation block number In the list of the allocation 
blocks belonging to this file, this number is the index of the first 
allocation block of the first extent descriptor of the extent record. 

Note 

Disks initialized using the enhanced Disk Initialization Manager 
introduced in system software version 7.0 might contain extent records 
for some blocks that do not belong to any actual file in the file system. 
These extent records have a file ID set to 5, indicating that the extent 
contains a bad block. See the chapter "Disk Initialization Manager" in 
this book for details on bad block sparing. ♦ 



Data Orga nization in Memory 

This section describes the data structures used internally by the FUe Manager and any 
external file system that accesses files on Macintosh-initialized volumes. As described in 
"Data Organization on Volumes/' which begins on page 2-52, most applications do not 
need to access these internal data structures directly. In general, you need to know about 
these data structures only if you are writing an external file system or a disk utility. 

A WARNING 

This section is provided primarily for informational purposes. The 

organization of data in memory is subject to change. If you want your 

application to be compatible with future versions of Macintosh system 

software, you should not access these internal data structures directly a 

The data struchires maintained in memory by the File Manager and external file 

systems include 

m tiie file I/O queue 

■ the volume control block queue, listing information about each mounted volume 

■ the file control block buffer, listing information about each access path to a fork 

■ a B*-tree control block for the catalog file and the extents overflow file for each 
mounted volume 

■ the drive queue, listing information about each drive connected to the Macintosh 



Field descriptions 

xkrKeyLen 

xkrFkType 

xkrFNum 
xkrFABN 
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The File I/O Queue 



The file I/O queue is a standard Operating Systeni queue (described in the chapter 
"Queue Utilities" in Inside Macintosh: Operating System Utilities) that contains parameter 
blocks for all asynchronous routines awaiting execution. 

Each entry in the file I/O queue consists of a parameter block for the routine that was 
called. The File Manager uses the first four fields of each parameter block in processing 
the I/O requests in the queue. 



TYPE ParamBlockRec = 
RECORD 

qLink: QElemPtr; 

qType: Integer; 

ioTrap: Integer; 

ioCmdAddr: Ptr; 



{next queue entry} 
{queue type) 
{routine trap} 
{routine address} 
{rest of block} 



END; 

Field descriptions 

qLink 
qType 
ioTrap 
ioCmdAddr 



A pointer to the next entry in the file I/O queue. 

The queue type. This field must always contain ORD { ioQType ) . 

The trap word of the routine that was called. 

The address of the routine that was called. 



You can get a pointer to the header of the file I/O queue by calling the File Manager 
utility function GetFSQHdr. 

Assembly-Language Note 

The global variable FSQHdr contains the header of the file I/O queue. ♦ 



Volume Control Blocks 



Each time a volume is mounted, the File Manager reads its volume information from the 
master directory block and uses the information to build a new volume control block 
(VCB) in the volume control blodk queue (unless an ejected or offline volimie is being 
remoimted). The File Manager also creates a volume buffer in the system heap. When a 
volume is placed offline, its buffer is released. When a volume is immounted, its VCB is 
removed from the VCB queue as well. 

Assembly-Language Note 

The global variable VCBQHdr contains the header of tfie VCB queue. The 
global variable Def VCBPtr points to the VCB of the default volume. ♦ 
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WARNING 

The size and structure of a VCB may be different in future versions of 
Macintosh system software. To ensure that you are reading the correct 
version of a VCB, check the vcbSigWord field; it should contam the 
value $4244. A 

The volume control block queue is a standard Operating System queue that's 
maintained in the system heap. It contains a volume control block for each mounted 
volume A volume control block is a nonrelocatable block that contains volume-specific 
information. The structure of a volume control block is defined by the VCB data type. 



TYPE VCB 
RECORD 
qLink: 
qType: 
vcbFlags: 
vcbSigWord: 
vcbCrDate: 
vcbLsMod : 
vcbAtrb: 
vcbNmFls : 
vcbVBMSt : 
vcbAllocPtr: 
vcbNmAlBlks: 
vcbAlBlkSiz: 
vcbClpSiz: 
vcbAlBlSt : 
vcbNxtCNID: 
vcbFreeBks : 
vcbVN: 
vcbDrvNum : 
vcbDRefNum: 
vcbFSID: 
vcbVRefNum: 
vcbMAdr : 
vcbBuf Adr: 
vcbMLen : 
vcbDirlndex: 
vcbDirBlk: 
vcbVolBkUp: 
vcbVSeqNum : 
vcbWrCnt : 
vcbXTClpSiz: 
vcbCTClpSiz: 
vcbNmRtDirs : 
vcbFilCnt: 



QElemPtr; 
Integer; 
Integer; 
Integer; 
LongInt ; 
Long In t ; 
Integer; 
Integer; 
Integer; 
Integers- 
Integer; 
LongInt ; 
LongInt ; 
Integer; 
LongInt; 
Integer; 
String [27] 
Integer; 
Integer; 
Integer; 
Integer; 
Ptr; 
Ptr; 

Integer; 
Integer; 
Integer; 
LongInt ; 
Integer; 
LongInt; 
LongInt ; 
LongInt ; 
Integer; 
LongInt ; 



{volume control block} 

{next queue entry) 
{queue type} 
{volume flags} 
{volume signature) 
{date and time of volume creation) 
{date and time of last modification) 
{volume attributes) 
{number of files in root directory) 
{first block of volume bitmap) 
{start of next allocation search) 
{number of allocation blocks in volume} 
{size (in bytes) of allocation blocks) 
{default clump size) 
{first allocation block in volume) 
{next unused catalog node ID) 
{number of unused allocation blocks) 
; {volume name) 

{drive number) 

{driver reference number) 

{file-system identifier) 

{volume reference number) 

{used internally} 

{used internally) 

{used internally) 

{used internally} 

{used internally) 

{date and time of last backup} 

{volume backup sequence number) 
{volume write count) 

{clump size for extents overflow file) 
{clump size for catalog file) 
{number of directories in root dir.) 
{number of files in volume) 
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vcbDirCnt : 
vcbFndrlnfo: 

vcbVCSize: 
vcbVBMCSiz 
vcbCtlCSiz 
vcbXTAlBks 
vcbCTAlBks 
vcbXTRef : 
vcbCTRef : 
vcbCtlBuf : 
vcbDirlDM: 
vcbOf f sM: 
END; 



Longint; {number of directories in volume) 

ARRAY [1.. 8] OF Longint; 

{information used by the Finder) 

Integer; {used internally) 

Integer; {used internally) 

Integer; {used internally) 

Integer; {size of extents overflow file) 

Integer; {size of catalog file) 

Integer; {ref. num. for extents overflow file} 

Integer; {ref. num. for catalog file) 

Ptr; {ptr. to extents and catalog caches) 

Longint; {directory last searched) 

Integer; {offspring index at last search) 



Note 

The values in the vcbNmAlBlks and vcbFreeBks fields are unsigned 
integers (that is, they can range from 0 to 65,535, not from -32,768 to 
32,767). Because Pascal does not support unsigned data types, you need 
to use the technique illustrated in "Delemuning the Amount of Free 
Space on a Volume" on page 2-46 to read the values in these fields 
correctly. ♦ 



Field descriptions 

qLink 



qType 

vcbFlags 

vcbSigWord 

vcbCrDate 

vcbLsMod 

vcbAtrb 



vcbNmFls 



A pointer to the next entry in the VCB queue. You can get a pointer 
to the header of the VCB queue by calling the File Manager utility 
function GetVCBQHdr. 

The queue type. When the volume is mounted and the VCB is 
created, this field is cleared. Thereafter, bit 7 of this field is set 
whenever a file on that volxime is opened. 
Volume flags. Bit 15 is set if the voltune information has been 
changed by a File Manager call since the volume was last affected 
by a FlushVol call. 

The volume signature. For HFS volumes, this field contains $4244. 

The date and time of volume creation (initialization). 

The date and time of last modification. This is not necessarily when 

the voltune was last flushed. 

Volume attributes. The bits have these meanings: 

Bit Meaning 

0-5 Reserved 

6 Set if the volume is busy (one or more files are open) 

7 Set if the volimr\e is locked by hardware 
8-14 Reserved 

15 Set if the volume is locked by software 

The number of files in the root directory. 
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vcbVBMSt 
vcbAllocPtr 
vcbNmAlBlks 
vcbAlBlkSiz 

vcbClpSiz 

vcbAlBlSt 

vcbNxtCNID 

vcbFreeBks 

vcbVN 



vcbDrvNum 



vcbDRefNum 



vcbFSID 

vcbVRefNum 

vcbMAdr 

vcbBuf Adr 

vcbMLen 

vcbDir Index 

vcbDirBlk 

vcbVblBkUp 

vcbVSeqNum 

vcbWrGnt 

vcbXTClpSiz 

vcbCTClpSiz 

vcbNmRtDirs 

vcbFilCnt 

vcbDirCnt 

vcbFndrlnfo 

vcbVCSize 

vcbVBMCSiz 

vcbCtlCSiz 



The first block of the volume bitmap. 

The start block of the next allocation search. Used internally. 

The number of allocation blocks in the volume. 

The allocation block size (in bytes). This value must always be a 

multiple of 512 bytes. 

The default clump size. 

The first allocation block *m the volume. 

The next unused catalog node ID (directory ID or file ID). 

The number of unused allocation blocks on the volume. 

The volume name. This field consists of a length byte followed 

by 27 bytes. Note that the volume name can occupy at most 

27 characters; this is an exception to the normal file and directory 

name limit of 31 characters. 

The drive number of the drive on which the volume is located. 
When a mounted volume is placed offline or ejected, vcbDrvNum is 
set to 0. 

The driver reference number of the driver used to access the 
volume. When a volume is ejected, vcbDRefNum is set to the 
previous value of vcbDrvNum (and hence is a positive number). 
When a volume is placed offline, vcbDRefNum is set to the 
negative of the previous value of vcbDrvNum (and hence is 
a negative number). 

An identifier for the file system handling the volume; it's zero for 

volumes handled by the File Manager and nonzero for volumes 

handled by other file systems. 

The volume reference number. 

Used internally. 

Used internally. 

Used internally. 

Used internally. 

Used internally. 

The date and time of the last volume backup. 

Used internally. 

The volume write count. 

The clump size of the extents overflow file. 

The clump size of the catalog file. 

The number of directories in the root directory. 

The number of files on the volume. 

The number of directories on the volume. 

Information used by the Finder. 

Used internally. 

Used internally. 

Used internally. 
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vcbXTAl Bks The size (in blocks) of the extents overflow file. 

vcbCTAlBks The size (in blocks) of the catalog file. 

vcbXTRe f The path reference number for the extents overflow file. 

vcbCTRef The path reference nun\ber for the catalog file. 

vcbC 1 1 Bu f A pointer to the extents and catalog caches. 

vcbDirlDM The directory last searched. 

vcbO f f sM The offspring index at the last search. 

File Control Blocks 

Each time a file is opened, the File Manager reads that file's catalog entry and builds a 
file control block (FCB) in the FCB buffer, which contains information about all access 
paths. The FCB buffer is a block in the system heap; the first word contains the length 
of the buffer, and the remainder of the buffer is used to hold FCBs for open files. 

The initial size of the FCB buffer is determined by the system startup information stored 
on a volume. Beginning in system software version 7.0, the File Manager attempts to 
resize the FCB buffer whenever the existing buffer is filled. 

You can find the beginning of any particular FCB by adding the size of all preceding 
FCBs to the size of the FCB buffer length word (that is, 2). This offset from the head of 
the FCB buffer is used as the file reference number of the corresponding open file. 
Because the current size of an FCB is 94 bytes, the first few valid file reference numbers 
are 2, 96, 190, 284, 378, 472, and so on. The maximum size of an expandable FCB buffer is 
32,535 bytes, so there is an absolute limit of 342 FCBs in the FCB buffer. 

Note 

The size and structure of an FCB will be different in future versions of 
Macintosh system software. To be safe, you should get information from 
the FCB allocated for an open file by calling the File Manager function 
PBGetFCBInf o. ♦ 

When you close a file (for example, by calling FSClose), the FCB for that file is cleared, 
and the File Manager may use that space to hold the FCB for a file that is opened at a 
later time. Consequently, it is important that you do not attempt to close a file more 
than once; you may inadvertently close a file that was opened by the system or by 
another application. 

WARNING ^ 

Closing a volume's catalog file (perhaps by inadvertentiy calling 
FSClose or PBCiose twice with the same file reference number) may 
result in damage to the volume's file system and loss of data. ▲ 

The structure of a file control block is defined by the FCB data type. 

TYPE FCB = {file control block} 
RECORD 

fcbFlNum: Longint ; {file ID} 

fcbFlags: Intieger; {file flags} 
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fcbSBlk: 
f cbEOF : 
fcbPLen: . 
fcbCrPs: 
fcbVPtr: 
fcbBfAdr: 
fcbFlPos : 
fcbClmpSize; 
fcbBTCBPtr: 
f cbExtRec : 
fcbFType: 
fcbCatPos: 
fcbDirlD: 
f cbCName : 
END; 



Integer; {reserved} 

Longint; {logical end-of-file} 

Longint; {physical end-of-file) 

Longint; {current file mark position) 

Ptr; {pointer to volxime control block) 

Ptr; {pointer to access path buffer) 

Integer; {reserved} 

Longint; {file clump size) 

Ptr; {pointer to B*-tree control block) 

ExtDataRec; {first three file extents) 

Longint; {file's four Finder type bytes) 

Longint; {catalog hint for use on close) 

Longint; {file's parent directory ID) 
String[31]; {name of file) 



Field descriptions 

f cbFlNum 
f cbFlags 



fcbSBlk 

fcbEOF 

fcbPLeri 

fcbCrPs 

fcbVPtr 

fcbBfAdr 
f cbFlPos 
f cbClmpSize 
fcbBTCBPtr 
fcbExtRec 



The file ID of this file. 

Rags describing the status of the file. Currently the following bits 
are defined: 

Bit Meaning 

0-7 Reserved 

8 Set if data can be written to the file 

9 Set if this FCB describes a resource fork 

10 Set if the file has a locked byte range 

11 Reserved 

12 Set if the fOe has shared write permissions 

13 Set if the file is locked (write-protected) 

14 Set if the file's clump size is specified in the FCB 

15 Set if the file has changed since it was last flushed 
Reserved. 

The logical end-of-file of the file. 
The physical end-of-file of the file. 
The position of the mark. 

A pointer to the volume control block of the volume containing 
the file. 

A pointer to the file's access path buffer. 
Reserved. 

The clump size of the file. 

A pointer to the file's B*-tree control block. 

An extent record (12 bytes) containing the first three extents of 

the file. 
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f cbFType The file's Finder type. 

f cbCatPos A catalog hint, used when you close the file, 

f cbDirlD The file's parent directory ID. 

f cbCName The file's name (as contained In the volun\e catalog file). 



B*-Tree Control Blocks 

When the File Manager mounts a volume, it reads the B*-tree header node for both the 
catalog file and the extents overflow file found on that volume and, for each file, creates 
a B*-tree control block in memory. (See the section "Header Nodes" on page 2-67 for a 
description of B*-tree header nodes.) The structure of a B*-tree control block is defined by 
the BTCB data type, 

TYPE BTCB = {B*-tree control block) 

RECORD 



btcFlags : 


SignedByte; 


{flag byte) 


btcResv: 


SignedByte; 


{ reserved} 


btcRef Num : 


Integer ; 


{file reference number) 


btcKeyCr : 


ProcPtr : 


{pointer to key comparison routine} 


btcCQPtr: 


Longint ; 


{pointer to cache queue} 


btcVarPtr: 


Long In t ; 


{pointer to B*-tree variables} 


btcLevel : 


Integer; 


{current level) 


btcNodeM: 


Longint; 


{current node mark) 


btcIndexM: 


Integer; 


{current index mark} 


btcDepth: 


Integer; 


{current depth of tree) 


btcRoot : 


Longint ; 


{number of root node} 


btcNRecs : 


Longint ; 


{number of leaf records in tree} 


btcFNode: 


Longint ; 


{number of first leaf node) 


btcLNode : 


Longint ; 


{number of last leaf node} 


btcNodeSize: 


integer; 


(size of a node} 


btcKeyLen: 


Integer ; 


{maximum length of a key} 


btcNNodes : 


Longint ; 


{total number of nodes in tree) 


btcFree; 


Longint ; 


{number of free nodes) 



END; 



Field descriptloris 

btcFlags A flag byte. Currently the following bits are defined: 



Bit Meaning 

4 Set if an existing index record must be deleted 

5 Set if a new index record must be created 

6 Set if the index key must be updated 

7 Set if the block has changed since it was last flushed 
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btcResv 
btcRefNum 

btcKeyCr 

btcCQPtr 

btcVarPtr 

btc Level 

btcNodeM 

btcIndexM 

bthDepth 

btcRoot 



btcNRecs 

btcFNode 

btcLNode 

btcNodeSize 

btcKeyLen 

btcNNodes 

btcFree 



Reserved. 

The file reference number of the catalog or extents overflow file 

corresponding to this control block. 

A pointer to the routine used to compare keys. 

A pointer to the cache queue. 

A pointer to B*-tree variables. 

The current level. 

The current node mark. 

The current index mark. 

The current depth of the B*-tree. 

The node number of the root node. The root node is the start of the 

B*-tree structure; usually the root node is the first index node, but 

it might be a leaf node if there are no index nodes. 

The number of data records (records contained in leaf nodes). 

The node number of the first leaf node. 

The node number of the last leaf node. 

The size (in bytes) of a node. Currently, this is always 512. 

The length of the key records in each node. 

The total number of nodes in the B*-tree. 

The total number of free nodes in the B*-tree. 



The Drive Queue 



The File Manager maintains a list of all disk drives connected to the computer. It 
maintains this list in the drive queue, which is a standard operating system queue. The 
drive queue is initially created at system startup time. Elements are added to the queue 
at system startup time or when you call the AddDr ive procedure. The drive queue can 
support any number of drives, limited only by memory space. Each element in the drive 
queue contains information about the corresponding drive; the structure of a drive 
queue element is defined by the DrvQEl data type. 

TYPE DrvQEl = 
RECORD 

qLink: QElemPtr; 

qType: Integer; 

dQDr ive : Integer ; 

dQRefNum: Integer; 

dQFSID: Integer; 

dQDrvSz : Integer ; 

dQDrvSz2: Integer; 
END; 



{next queue ent:ry} 

(flag for dQDrvSz and dQDrvSz?} 

{drive number} 

{driver reference number} 

{file-system identifier} 

{number of logical blocks on drive} 

{additional field for large drives} 
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Field descriptions 

qLink A pointer to the next entry in the drive queue. 

qType Used to specify the size of the drive. If the value of qType is 0, 

the number of logical blocks on the drive is contained in the 
dQDrvSz field alone. If the value of qType is 1, both dQDrvSz 
and dQDrvSz2 are used to store the number of blocks; in that case, 
dQDrvSz2 contair\s the high-order word of this number 
and dQDrvSz contains the low-order word. 

dQDriye The drive number of the drive. 

dQRe f Num The driver reference number of the driver controlling the device on 

which the volume is mounted. 
dQFSID An identifier for the file system handling the volume in the drive; 

it's zero for volumes handled by the File Manager and nonzero for 

volumes handled by other file systems. 
dQDrvS z The number of logical blocks on the drive. 

dQDrvSz2 An additional field to handle large drives. This field is used only if 

the qType field contains 1. 
The File Manager also maintains four flag bytes preceding each drive queue element. 
These bytes contain the following information: 

Byte Contents 

0 Bit 7=1 if the voliune on the drive is locked 

1 0 if no disk in drive; 1 or 2 if disk in drive; 8 if nonejectable disk in drive; 
$FC-$FF if disk was ejected within last 1.5 seconds; $48 if disk in drive is 
nonejectable but driver wants a call 

2 Used internally during system startup 

3 Bit 7=0 if disk is single-sided 

You can read these flags by subtracting 4 bytes from the begiiming of a drive queue 
element, as illustrated in Listing 2-11. 



Listing 2-1 1 Reading a drive queue element's flag bytes 

FUNCTION GetDriveFlags (myDQElemPtr : DrvQElPtr) : Longint; 
TYPE 

" FlagPtr = '^Longint; {pointer to the queue element flag bytes) 
VAR 

myQFlagsPtr: FlagPtr; 
BEGIN 

{Just subtract 4 from the queue element pointer.) 
myQFlagsPtr := FlagPtr (0RD4 (myDQElemPtr) - 4); 
GetDriveFlags := myQFlagsPtr'"; 
END; 
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The GetDriveFlags function defined Listing 2-11 takes a pointer to a dnve queue 
element as a parameter. You can get a queue element pointer for a particular volume by 
walking the drive queue untU you find a queue element whose dQDrive field contams 
the same value as the vcbDrvNum field of that volume's VCB. You can get a pomter to 
the header of the drive queue by calling the File Manager hinction GetDrvQHdr. 
Note that the bit numbers given in this section use the standard MC68000 numbering 
scheme; to access the correct bit using some Pascal routines, you must reverse that 
numbering. For example, if you use the Toolbox BitTst routine to determine whether a 
particular disk is single^ided, you must test bit 24 (that is, 31 minus 7) of the rehimed 
long integer. If you use the built-in Pascal hmction BTST, however, you can test the 
indicated bit directly. 

Assembly-Language Mote 

The global variable DrvQHdr contains the header of the drive queue. ♦ 



File Manager Reference 



This section describes the routines provided by the File Manager and the data structures 
you must pass when calling those routines. 

The "Data Structures" section shows the Pascal data structures for all the records and 
parameter blocks that most appUcations are likely to use. If you need information about 
data structures describing the structure of the information maintained on volumes or m 
memory, see "Data Organization on Volumes" and "Data Organization m Memory" 
earlier in this chapter. 

The remaining sections describe the routines provided by the File Manager. 



Data Structures 

This section describes the data structures that your application uses to exchange 
information wid\ the File Manager. 



File System Specification Record 



The system software recognizes the file system specification record, which provides a 
simple, standard way to specify the name and location of a file or directory. The file 
system specification record is defiiied by the FSSpec date type. 



TYPE FSSpec = 
RECORD 

vRefNum: 
. parlD: 

ncime: 
END; 



{file system specification) 

Integer; {volume reference number) 
Longint; {diirectory ID of parent directory) 
Str63; {filename or directory name) 
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Field descriptions 

vRefNum 



parlD 



name 



The volume reference number of the volume containing the specified 
file or directory. 

The directory ID of the directory contairung the specified file or 
directory. 

The name of the specified file or directory. 
The FSSpec record can describe only a file or a directory, not a volume. A volume can 
be identified by its root directory, although the system software never uses an FSSpec 
record to describe a volume. (The directory ID of the root's parent directory is 
f sRtParlD, defined in the interface files. The name of the root directory is the same 
as the name of the volume.) 

If you need to convert a file specification into an FSSpec record, call the function 
FSMakeFSSpec. Do not fill in the fields of an FSSpec record yourself. 



Basic File Manager Parameter Block 



Many of the low-level hmctions that manipulate files and volumes exchange information 
with your application using the basic File Manager parameter block, defined by the 
ParamBlockRec data type. 



TYPE ParamBlockRec = 
RECORD 

qLink: QElemPtr; 

qType: Integer ; 

ioTrap: Integer; 

ioCmdAddr: Ptr; 

ioComplet ion : ProcPt r ; 

ioResult: OSErr; 

ioNamePtr: StringPtr; 

ioVRefNum: Integer; 
CASE ParairiBlkType OF 
ioParam: 



(basic File Manager parameter block) 

{next queue entry) 

{queue type) 

(routine trap) 

(routine address) 

(pointer to completion routine) 

(result code) 

(pointer to pathname) 

(volume specification) 



(ipRefNum: 


Integer; 


. (file reference number) 


ioVer sN\iin ; 


SignedByte; 


{ version number) 


ioPermssn: 


'* SignedByte; 


(read/write permission) 


ioMisc: 


Ptr; 


(miscellaneous ) 


ioBuf f er : 


Ptr; 


(data buffer) 


ioReqCount : 


Longint ; 


(requested number of bytes) 


ioActCount : 


Longint ; 


(actual number of bytes) 


ioPosMode: 


Integer; 


(positioning mode and newline char.) 


ioPosOf f set : 


Longint) ; 


(positioning offset) 


.leParam: 






(ioFRefNum: 


Integer; 


(file reference number) 


ioFVersNum: 


SignedByte; 


{file version number (unused)) 
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fillerl: 
ioFDirlndex: 
ioFlAttrib: 
ioFlVersNum: 
ioFlFndrlnfo: 
ioFlNum: 
ioFlStBlk: 
ioFlLgLen: 
ioFlPyLen: 
ioFlRStBlk: 
ioFlRLgLen: 
ioFlRPyLen: 
ioFlCrDat : 
ioFlMdDat : 
volumeParam: 
(f iller2 : 
ioVol Index: 
ioVCrDate: 
ioVLsBkUp: 
ioVAtrb: 
ioVNmFls : 
ioVDirSt : 
ioVBlLn: 
ioVNmAlBlks : 
ioVAlBlkSiz : 
ioVClpSiz : 
ioAlBlSt: 
ioVNxtFNum: 
ioVFrBlk: 
END; 



SignedByte; 
Integer ; 
SignedByte; 
SigriedByte; 
FInfo; 
LongInt ; 
Integer; 
LongInt ; 
LongInt ; 
Integer; 
LongInt ; 
LongInt ; 
LongInt ; 
LongInt) ; 

LongInt ; 
Integer; 
LongInt ; 
LongInt ; 
Integer; 
Integer; 
Integer; 
Integer; 
Integer; 
LongInt ; 
LongInt ; 
Integer; 
LongInt ; 
Integer) ; 



The first eight fields are common 
unique fields. 



{ reserved} 

{directory index} 

{file attributes} 

{file version number (unused)} 

{information used by the Finder} 

{file ID} 

{first alloc, blk. of data fork} 

{logical EOF of data fork} 

{physical EOF of data fork} 

{first alloc, blk. of resource fork} 

{logical EOF of resource fork} 

{physical EOF of resource fork} 

{date and time of creation} 

{date and time of last modification} 

{reserved} 
{volume index} 

{date and time of initialization} 
{date and time of last modification} 
{volume attributes} 
{number of files in root directory} 
{first block of directory} 
{length of directory in blocks} 
{number of allocation blocks} 
{size of allocation blocks} 

{default clump size} 

{first block in block map} 

{next unused file ID} 

{number of unused allocation blocks} 

to all three variants: Each variant also includes its own 



Field descriptions for fields common to all variants 



qLink 



qType 
ioTrap 

ioCmdAddr 



A pointer to the next entry in the file I/O queue. (This field is used 
internally by the File Manager to keep track of asynchronous calls 
awaiting execution.) 

The queue type. (This field is used internally by the FUe Manager.) 
The trap number of the routine that was called. (This field is used 
internally by the File Manager.) 

The address of the routine that was called. (This field is used 
internally by the File Manager.) 
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ioCompletion 



ioResult 



ioNamePtr 



ioVRefNum 



A pointer to a completion routine to be executed at the end of an 
asynchronous call. It should be NIL for asynchronous calls with 
no completion routine and is automatically set to NIL for all 
synchronous calls. See "Completion Routines" on page 2-238 for 
information about completion routines. 

The result code of the function. For synchronous calls, this field is 
the same as the result code of the function call itself, to determine 
when an asynchronous call has actually been completed, your 
application can poll this field; it's set to a positive number when 
the call is made and receives the actual result code when the call 
is completed. 

A pointer to a pathname. Whenever a routine description specifies 
that ioNamePtr is used— whether for input, output, or both— 
it's very important that you set this field to point to storage for a 
Str255 value (if you're using a pathname) or to NIL (if you're not). 
A volume specification (volume reference number, working 
directory reference number, drive number, or 0 for default volume). 



I 



Field descriptions 

ioRefNum 
ioVersNum 

ioPermssn 
ioMisc 



ioBuf f er 

ioReqCount 
ioActCount 
ioPosMode 



for th6 ioParam variant 

The file reference number of an open file. 

A version number. This field is no longer used and you should 

always set it to 0. 

The access mode. 

Depends on the routine called. This field contains either a new 
logical end-of-file, a new version number, or a pointer to a new 
pathname. Because ioMisc is of type Ptr, you'll need to perform 
type coercion to interpret the value of ioMisc correctly when it 
contains an end-of-file (a Longlnt value) or version number (a 
SignedByte value). 

A pointer to a data buffer into which data is written by _Read calls 

and from which data is read by _Wr i t e calls. 

The requested number of bytes to be read, written, or allocated. 

The number of bytes actually read, written, or allocated. 

The positiorung mode for setting the mark. Bits 0 and 1 of this field 

indicate how to position the mark; you can use the following 

predefined constants to set or test their value: 



CONST 

fsAtMark 
fsFromStart 
f sFromLEOF 
f sFrQmMark 



= 0; {at current mark} 

= 1; {from beginning of file) 

= 2; {from logical end-of-file) 

= 3; {relative to current mark) 



You can set bit 4 of the ioPosMode field to request that the data be 
cached, and you can set bit 5 to request that the data not be cached. 
You can set bit 6 to request that any data written be immediately 
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read; this ensures that the data written to a volume exactly matches 
the data in memory. To request a read-verify operation, add the 
following constant to the positioning mode: 



64; [use read-verify mode) 



ioPosOf f set 

Reld descriptions 

ioFRefNum 
ioFVersNum 

f illerl 

ioFDirlndex 

ioFlAttrib 



ioFlVersNum' 

ioFlFndrInf o 

ioFlNum 
ioFlStBlk 

ioFlLgLen 
ioFlPyLen 
ioFlRStBlk 

ioFlRLgLen 
ioFlRPyLen 
ioFlCrDat 

ioFlMdDat 



CONST 

rdVerify 

You can set bit 7 to read a continuous stream of bytes, and place 
the ASCn code of a newline character in the high-order byte to 
terminate a read operation at the end of a line. 
The offset to be used in conjunction with the positioning mode. 

for the f ileParam variant 

The file reference number of an open file. 

A file version number. This field is no longer used and you should 

always set it to 0. 

Reserxred. 

An index for use with the PBHGetFInf o function. 

File attributes. The bits in this field have these meanings: 

Bit Meaning 

0 Set if file is locked 

2 Set if resource fork is open 

3 Set if data fork is open 

4 Set if a directory 

7 Set if file (either fork) is open 

A file version number This feature is no longer supported, and you 
must always set this field to 0. 

Information used by the Finder. (See the chapter 'Tinder Interface" 
in Inside Macintosh: Macintosh Toolbox Essentials for details.) 

Afileia 

The first allocation block of the data fork. This field contains 0 if the 
file's data fork is empty. 
The logical end-of-file of the data fork. 
The physical end-of-file of the data fork. 

The first allocation block of the resource fork. This field contains 0 if 
the file's resource fork is empty. 
The logical end-of-file of the resource fork. 
The physical end-of-file of the resource fork. 
The date and time of the file's creation, specified in seconds since 
midnight, January 1, 1904. 

The date and time of the last modification to the file, specified in 
seconds since midnight, January 1 , 1904. 



2-90 File Manager Reference 



TIVO-408540 



CHAPTER 2 



File Manager 



Field descriptions 

filler2 
ioVolIndex 
ioVCrDate 
ioVLsBkUp 



ioVAtrb 

ioVNmFls 

ioVDirSt 

ioVBlLn 

ioVNmAlBlks 

ioVAlBlkSiz 

ioVClpSiz 

ioAlBlSt 

ioVNxtFNum 

ioVFrBlk 



for the voiumeParam variant 
Reserved. 
The volume index. 

The date and time of volume initialization. 

The date and time the volume information was last modified. (This 

field is not char\ged when information is written to a file and does 

not necessarily indicate when the volume was flushed.) 

The volume attributes. 

The number of files in the root directory. 

The first block of the volume directory. 

Length of directory in blocks. 

The number of allocation blocks. 

The size of allocation blocks. 

The volume dump size. 

The first block in the volume map. 

The next unused file number. 

The number of unused allocation blocks. 



HFS Parameter Block 



Most of the low-level HFS functions exchange information with your appUcation using 
the HFS parameter block, defined by the HParamBlockRec data type. 



TYPE HParamBlockRec 
RECORD 
qLink : 
qType: 
ioTrap: 
ioCmdAddr : 
ioCompletion : 
ioResult : 
ioNamePtr : 
ioVRefNum: 
CASE ParamBlkType 
ioParam: 
(ioRefNum: 
ioVersNum: 
ioPermssn: 
ioMisc: 
ioBuf fer : 
ioReqCount : 
ioActCOunt : 
ioPosMode : 
ioPosOffset: 



~ {HFS parameter block) 

QElemPtr; {next queue entry) 

Integer; {queue type) 

Integer; {routine trap) 

Ptr; {routine address) 

ProcPtr; {pointer to completion routine) 

OSErr; {result code) 

StringPtr; {pointer to pathname) 

Integer; {volume specification) 



OF 



Integer; (file reference niimber) 

SignedByte; {version number) 

SignedByte; {read/write permission) 

Ptr; {miscellaneous) 

Ptr; {data buffer) 

Longint; {requested number of bytes) 

Longint; {actual number of bytes) 

Integer; {positioning mode and newline char.) 

Longint); {positioning offset) 
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f ileParam': 



ioFRefNum: 


Integer; 


I^LlJ-e ]_ e i- tri. cllt-t; liu.iiiuc:j. / 


ioFVersNum: 


SignedByte; 


1^ j3--Le veirt>xuii iilhuucj. V"-*^*'-**^^^/ j 


fillerl: 


SignedByte; 


(reserved) 


ioFDirlndex: 


Integer; 


iOireccory inuexj 


ioFlAttrib: 


SignedByte; 




ioFlVersNum: 


SignedByte; 


l^tiie version nuinoci. vunutacuj / 


ioFlFndrinfo: 


FInfo; 


{ mtormat ion useu oy cue riiiutiLj 


ioDirlD: 


Longint ; 


{directory ID or file ID) 


ioFlStBlk: 


Integer; 


{first alloc, blk. of data fork) 


ioFlLgLen; 


Longint ; 


{logical EOF of data fork) 


ioFlPyLen: 


Longint; 


(physical EOF of data fork) 


ioFlRStBlk: 


Integer; 


(first alloc, blk. of resource fork] 


ioFlRLgLen: 


Longint ; 


{logical EOF of resource fork) 


ioFlRPyLen: 


Longint ; 


{physical EOF of resource fork) 


ioFlCrDat : 


Longint; 


(date and time of creation) 


ioFlMdDat : 


Longint) ; 


[date and time of last modification) 



volumeParam: 



filler2: 


Longint ; 


{reserved) 


ioVol Index: 


Integer; 


{volume index) 


ioVCrDate: 


Longint ; 


(date and time of initialization) 


ioVLsMod: 


Longint ; 


(date and time of last modification) 


ioVAtrb: 


Integer; 


(volume attributes) 


ioVNmFls : 


Integer; 


(number of files in root directory) 


ioVBitMap: 


Integer; 


(first block of volume bitmap) 


ioAllocPtr: 


Integer; 


(first block of next new file) 


ioVNmAlBlks : 


Integer; 


{number of allocation blocks) 


ioVAlBlkSiz: 


Longint ; 


(size of allocation blocks) 


ioVClpSiz: 


Longint ; 


(default clump size) 


ioAlBlSt : 


Integer; 


(first block in volume map) 


ioVNxtCNID: 


Longint; 


(next unused node ID) 


ioVFrBlk: 


Integer; 


(number of unused allocation blocks; 


ioVSigWord: 


Integer; 


(volume signature) 


ioVDrvInfo: 


Integer; 


(drive number) 


ioVDRefNum: 


Integer; 


(driver reference number) 


ioVFSID: 


Integer; 


(file-system identifier) 


ioVBkUp: 


Longint ; 


(date and time of last backup) 


ioVSeqNum: 


Integer; 


(used internally) 


ioVWrCnt : 


Longint; 


(volume write count) 


ioVFilCnt : 


Longint ; 


(number of files on volume) 


ioVDirCnt : 


Longint; 


(number of directories on volume) 


ioVFndrlnfo: 


ARRAY [1. .8] 


OF Longint) ; 






(information used by the Finder) 


ccessParam: 






(filler3: 


Integer; 


{reserved} 
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ioDenyModes : 
filler4: 
fillers: 
ioACUser : 
fillers: 
ioACOwnerlD: 
ioACGroupID: 
ioACAccess : 
obj Pa ram: 
(filler?: 
ioObjType: 
ioObjNamePtr : 
ioObjID: 
copyParam: 

(ioDstVRefNum: 
fillers: 
ioNewName : 
ioCopyName : 
ioNewDirlD: 
wdParam: 
(f iller9: 
ioWDIndex: 
ioWDProcID: 
ioWDVRefNum: 
fillerlO: 
f illerll: 
fillerl2: 
fillerl3: 
ioWDDirlD: 
f idParam: 
(.fillerl4: 
ioDestNamePtr : 
fillerlS: 
ioDestDirlD: 
fillerl6: 
fillerl?: 
ioSrcDirlD: 
fillerlS: 
ioFilelD: 
csParam: 

(ioMatchPtr: 
ioReqMatchCount 
ioActMatchCount 
ioSearchBits : 
ioSearchInf ol : 



Integer; {access mode information] ^ 

Integer ; { reserved) 

SignedByte; {reserved} 

SignedByte; {user access rights) 

Longint ; { reserved) 

Longint; {owner ID) 

Longint; {group ID) 

Longint) ; {directory access rights) 

Integer; {reserved) 

Integer; {function code) 

Ptr; {ptr to returned creator/group name) 

Longint) ; {creator/group ID) 

Integer; {destination volume identifier) 

Integer; {reserved} 

Ptr; {pointer to destination pathname} 

Ptr; {pointer to optional name] 

Longint) ; ' {destination directory ID) 

Integer; {reserved} 

Integer; {working directory index) 

Longint; {working directory user identifier} 

Integer; {working directory's vol. ref- num.} 

Integer; {reserved} 

Longint; {reserved) 

Longint; {reserved} 

Longint ; {reserved} 

Longint); {working directory's directory ID) 

Longint ; {reserved) 

StringPtr; {pointer to destination filename] 

Longint; {reserved] 

Longint; {destination parent directory ID} 

Longint; {reserved] 

Longint; {reserved] 

Longint; {source parent directory ID] 

Integer; {reserved] 

Longint) ; {file ID] 

FSSpecArrayPtr; {pointer to array of matches] 

Longint; {max. nxamber of matches to. return] . 

Longint; {actual number of matches] 

Longint; {enable bits for matching rules] 
CInfoPBPtr; {pointer to values and lower bounds] 
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ioSearchInf o2 : 
ioSearchTime: 
ioCatPosition: 
ioOptBuf f er: 
ioOptBuf Size: 
f oreignPrivParam : 
(filler21: 
firier22: 

ioForeignPrivBuf f er : 
ioForeignPrivReqCount 
ioForeignPrivActCount 
filler23: 

ioForeignPrivDirlD : 



ioForeignPrivInf ol 
ioForeignPrivInf o2 
ioForeignPrivInf o3 
ioForeignPr ivInfo4 : 
END; 



CInfoPBPtr; 
Longint ; 
CatPositionRec ; 
Ptr; 

Longlnt) ; 



Longint ; 
Longint ; 
Ptr ; 

Longint; 
Longint ; 
Longint ; 
Longint ; 

Longint 
Longint 
Longint 
Longint) 



(pointer to masks and upper bounds) 
{maximum time to search} 
{current catalog position) 
(pointer to optional read buffer) 
{length of optional read buffer) 

{reserved) 
{ reserved) 

{privileges data buffer) 
{size of buffer) 
{amount of buffer used) 
{reserved) 

{parent directory ID of ) 
( foreign file or directory) 
{privileges data) 
{privileges data) 
{privileges data) 
; {privileges data) 



The first eight fields are common to all ten variants. Each variant also includes its own 
unique fields. 

Field descriptions common to all variants 



qLink 

qType 
ioTrap 

ioCmdAddr 

ioCompletion 



ioResult 



ioNamePtr 



A pointer to the next entry in the file I/O queue. (This field is used 
internally by the File Manager to keep track of asynchronous calls 
awaiting execution.) 

The queue type. (This field is used internally by the FOe Manager.) 
The trap number of the routine that was called. (This field is used 
internally by the File Manager.) 

The address of the routine that was called. (This field is used 
internally by the File Manager.) 

A poiiiter to a completion routine to be executed at the end of an 
asynchronous call. It should be NIL for asynchronous calls with 
no completion routine and is automatically set to NIL for all 
synchronous calls. See "Completion Routines" on page 2-238 for 
information about completion routines. 

The result code of the function. For synchronous calls, this field is 
the same as the result code of the function call itself. To determine 
when an asynchronous call has actually been completed, your 
application can poll this field; it's set to a positive number when 
the call is made and receives the actual result code when the call 
is completed. 

A pointer to a pathname. Whenever a routine description specifies 
that ioNamePtr is used — whether for input, output, or both — it's 
very important that you set this field to point to storage for a 
Str255 value (if you're using a pathname) or to, NIL (if you're not)^ 
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ioVRefNum 

Field descriptions 

ioRefNum 
ioVersNuin 

ioPermssn 
ioMisc 



ioBuf f er- 

ioRejiCount 
iOActCount 
ioPosMode 



A volume specification (volume reference number, v^orking 
directory reference number, drive number, or 0 for default volume). 

for the ioParam variant 

The file reference number of an open file. 

A version number. This field is no longer used and you should 

always set it to 0. 

The access mode. 

Depends on the routine called. This field contains either a new 

logical end-of-file, a new version number, a pointer to an access 

path buffer, or a pointer to a new pathname. Because ioMisc is of 

type Ptr, you'll need to perform type coercion to interpret the value 

of ioMisc correctly when it contains an end-of-file (a Longint 

value) or version number (a SignedByte value). 

A pointer to a data buffer into which data is written by _Read calls 

and from which data is read by _Write calls. 

The requested number of bytes to be read, written, or allocated. 

The number of bytes actually read, written, or allocated. 

The positioning mode for setting the mark. Bits 0 and 1 of this field 

indicate how to position the mark; you can use the following 

predefined constants to set or test their value: 



CONST 

f sAtMark 
f sFromStart 
f sFromLEOF 
f sFromMark 



0; {at current mark} 

1; {from beginning of file) 

= 2; {from logical end-of-file) 

= 3; {relative to current mark} 



You can set bit 4 of the ioPosMode field to request that the data be 
cached, and you can set bit 5 to request that the data not be cached. 
You can set bit 6 to request that any data written be immediately 
read; this ensiues that the data written to a volume exactly matches 
the data in memory. To request a read-verify operation, add the 
following constant to the positioning mode: 



ioPosOf f set 



CONST 

rdVerify 



= 64; 



{use read-verify mode) 



You can set bit 7 to read a continuous stream of bytes, and place the 
ASCII code of a newline character in the high-order byte to 
terminate a read operation at the end of a line. 
The offset to be used in conjimction with the positiorung mode. 



Field descriptions for the f ileParam variant 

ioFRef Num The Ble reference number of an open file. 

ioFVer sNum A file version number. This field is no longer used and you should 

always set it to 0. 
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f illerl 

ioFDirlndex 

ioFlAttrib 



ioFlVersNum 

ioFlFndrlnfo 

ioDirlD 

ioFlStBlk 

ioFlLgLen 

ioFlPyLen 

ioFlRStBlk 

ioFlRLgLen 

ioFlRPyLen 

ioFlCrDat 

ioFlMdDat 

Field descriptions 

filler2 
ioVol Index 
ioVCrDate 
ioVLsMod 

ioVAtrb 

ioVNniFls 

ioVBitMap 

ioAllocPtr 

ioVNmAlBlks 

ioVAlBlkSiz 

ioVClpSiz 

ioAlBlSt 

ioVNxtCNID 

ioVFrBlk 



Reserved. 

An index for use with the PBHGetFInf o function. 

File attributes. The bits in this field have these meanings: 

Bit Meaning 

0 Set if file is locked 

2 Set if resource fork is open 

3 Set if data fork is open 

4 Set if a directory 

7 Set if file (either fork) is open 

A file version number. This field is no longer used and you should 
alv^ays set it to 0. 

Information used by the Finder. 

A directory ID. 

The first allocation block of the data fork. This field contains 0 if the 
file's data fork is empty. 

The logical end-of-file of the data fork. 

The physical end-of-file of the data fork. . 

The first allocation block of the resource fork. 

The logical end-of-file of the resource fork. 

The physical end-of-file of the resource fork. 

The date and time of the file's creation, specified in seconds since 

midnight, January 1, 1904. 

The date and time of the last modification to the file, specified in 
seconds since midnight, January 1, 1904. 

for the voluroeParain variant 
Reserved. 

An index for use with the PBHGetVInf o function. 
The date and time of volume initialization. 

The date and time the volume information was last modified. (This 
field is not dianged when information is written to a file and does 
not necessarily indicate when the volume was flushed.) 

The volume attributes. 

The number of files in the root directory. 

The first block of the volume bitmap. 

The block at which the next new file starts. Used intemally 

The number of allocation blocks. 

The size of allocation blocks. 

The cluiTip size. 

The first block in the volume map. 
The next unused catalog node ID. 
The number of unused allocation blocks. 
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ioVSigWord A signature word identifying the type of volume; it's $D2D7 for 

MFS volumes and $4244 for volumes that support HFS calls. 
ioVDrvInfo The drive number of the drive containing the volume. 

ioVDRe f Num For online volumes, the reference number of the I/O driver for the 

drive identified by ioVDrvInf o. 
ioVFSiD The file-system identifier. It indicates which file system is servicing 

the volume; it's zero for File Manager volumes and nonzero for 

volumes handled by an external file system. 
ioVBkUp The date and time the volume was last backed up (it's 0 if never 

backed up). 

ioVSeqNum Used internally. 

ioVWrCnt The volume write count, 

ioVFi ICnt The total number of files on the volume. 

ioVDirCnt The total number of directories (not including the root directory) on 

the volume. 

ioVFndrInf o Information used by the Finder. 

Field descriptions for the accessParam variant 
fillers Reserved. 

ioDeny Modes Access mode information. The bits in this field have these meanings: 



Bit Meaning 

0 If set, request read permission 

1 If set, request write permission 
2-3 Reserved; must be 0 

4 If set, deny other readers access to this file 

5 If set, deny other writers access to this file 
6-15 Reserved; must be 0 



filler4 Reserved, 
fillers Reserved. 

ioACUser The user's access rights for the specified directory. The bits in this 

field have the follov^g meanings: 



Bit Meaning 

0 S6t if user does not have See Folder privileges 

1 Set if user does not have See Files privileges 

2 Set if user does not have Make Changes privileges 
3-6 Reserved; alv/ays set to 0 

7 Set if user is not owner of the directory 



f i 1 ler 6 Reserved. 
ioACOwnerlD The owner ID. 
ioACGroupID The group ID. 

ioACAccess The directory access privileges. See the section "Directory Access 

Privileges/' beginning on page 2-18, for a complete description of 
this field. 
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Field descriptions for the objParam variant 



filler? 
ioObjType 

ioObjNamePtr 
ioObjID 



Reserved. 

A function code. The values passed in this field are determined by 
the routine to which you pass this parameter block. 
A pointer to the returned creator/ group name. 
The creator/group ID. 



Raid descriptions for the copypar am variant 

ioDstVRef Num A volume reference number for the destination volume, 

fillers Reserved- 

ioNewName A pointer to the destination pathname. 

ioCopyName A pointer to an optional name. 

ioNewDir ID A destination directory ID. 

Field descriptions for the wdParam variant 

filler9 Reserved. 

ioWDIndex An index to working directories. 

ioWDPr DC ID The working directory user identifier. 

ioWDVRef Num The volume reference number for the vyorking directory. 

filler 10 Reserved, 

fillerll Reserved. 

filler 12 Reserved. 

fillerl3 Reserved. 

ioWDDirlD The working directory's directory ID. 



Field descriptions for the f idParam variant 



f illerl4 

ioDestNamePtr 

fillerlS 

ioDestDirlD 

fillerie 

f illerl7 

ioSrcDirlD 

fillerie 

ioFilelD 



Reserved. 

A pointer to the name of the destination file. 
Reserved. 

The parent directory ID of the destination file. 

Reserved. 

Reserved. 

The parent directory ID of the source file. 

Reserved. 

The file ID. 



Field descriptions for the c sPar am variant 

ioMatchPtr A pointer to an array of FSSpec records in which the file and 

directory names that match the selection criteria are returned. The 
array must be large enough to hold the largest possible number of 
FSSpec records, as determined by the ioReqMatchCount field. 



ioReqMatchCount 



The maximum number of matches to return. This number should be 
the number of FSSpec records that will fit in the memory pointed 
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ioActMat chCount 
ioSearchBits 

ioSearchlnfol 
ioSearchInf o2 
ioSearchTime 



ioCatPosition 



ioOptBuf fer 



iobptBufSize 



to by ioMatchPtr. You can use this field to avoid a possible excess 
of matches for criteria that prove to be too general (or to limit the 
length of a search if the ioSearchTime field isn't used). 

The number of actual matches found. 

The fields of the parameter blocks ioSearchlnfol and 
ioSearchInfo2 that are relevant to the search- See "Searching a 
Volume" beginning on page 2-38 for constants you can add to 
determine a value for ioSearchBits. 

A pointer to a CInf oPBRec parameter block that contains values 
and the lower bounds of ranges for the fields selected by 
ioSearchBits. 

A pointer to a second CInf oPBRec parameter block that contains 
masks and upper bounds of ranges for the fields selected by 
ioSearchBits. 

A time limit on a search, in Time Manager format. Use this field to. 
limit the run time of a single call to PBCatSearch. A value of 0 
imposes no time limit. If the value of this field is positive, it is 
interpreted as milliseconds. If the value of this field is negative, it is 
interpreted as negated microseconds. 

A position in the catalog where searching should begin. Use this 
field to keep an index into the catalog when breaking down the 
PBCatSearch search into a number of smaller searches. This field 
is valid whenever PBCatSearch exits because it either spends the 
maximum time allowed by ioSearchTime or finds the maximum 
number of matches allowed by ioReqMatchCount. 

To start at the beginning of the catalog, set the initialize 
field of ioCatPosition to 0. Before exiting after an interrupted 
search, PBCatSearch sets that field to the next catalog entry to 
be searched. 

To resume where the previous call stopped, pass the entire 
Cat Posit ion record returned by the previous call as input 
to the next. 

A pointer to an optional read buffer. The ioOpt Buff er and 
ioOptBu f Si ze fields let you specify a part of memory as a read 
buffer, increasing search speed. 

The size of the buffer pointed to by ioOpt Bu f fer. Buffer size 
effectiveness varies with models and configurations, but a 16 KB 
buffer is likely to be optimal. The size should be at least 1024 bytes 
and should be an integral multiple of 512 bytes. 



Field descriptions for the f oreignPrivParam variant 
filler21 Reserved, 
filler 22 Reserved. 

ioForeignPr ivBuf f er 

A pointer to a buffer containing access-control information about 
the foreign file system. 
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ioForeignPrivReqCount 

The size of the buffer pointed to by the ioForeignPr ivBuf f er field. 

ioForeignPrivActCount 

The amount of the buffer pointed to by the ioForeignPrivBuf f er 

field that was actually used to hold data, 

fill er 2 3 Reserved. 

ioForeignPrivDirlD 

The parent directory ID of the foreign file or directory. 

ioForeignPrivInfol 

A long word that may contain privileges data. 

ioForeignPrivInfo2 

A long word that may contain privileges data. 

ioForeignPrivInf o3 

A long word that may contain privileges data, 

ioForeignPrivInf o4 

A long word that may contain privileges data. 

Catalog Information Parameter Blocks 

The low-level functions PBGetCat Inf o, PBSetCatInf o, and PBCat Search exchange 
information with your application using the catalog information parameter block, which is 
defined by the CInf oPBRec data type. There are two variants of this record, hFileInf o 
and dirinf which describe files and directories, respectively. 

TYPE CInfoPBRec = {catalog information parameter block} 
RECORD 



qLink: 


QElemPtr ; 


{next queue entry} 


qType: 


Integer; 


{queue type} 


ioTrap: 


Integer; 


{routine trap} 


ioCmdAddr : 


Ptr; 


{routine address} 


ioCompletion: 


ProcPtr ; 


{pointer to completion routine} 


ioResult : 


OSErr; 


{result code} 


ioNamePtr : 


StringPtr; 


{pointer to pathname} 


ioVRefNum: 


Integer ; 


{volume specification} 


ioFRefNum: 


Integer; 


{file reference number) 


ioFVersNum : 


SignedByte; 


{version number} 


Eillerl: 


SignedByte; 


{reserved} 


ioFDir Index: 


Integer; 


{directory index} 


ioFlAttrib: 


SignedByte; 


{file or directory attributes} 


ioACUser : 


SignedByte; 


{directory access rights} 



CASE CInfoType OF 
hFileInf o: 

(ioFlFndrlnfo: FInfo; {information used by the Finder} 

ioDirlD: Longint ; {directory ID or file ID) 

ioFlStBlk: Integer; {first alloc, blk. of data fork} 
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ioFlLgLen : 


Longint ; 


{logical EOF of data fork} 


ioFlPyLen: 


Long In t ; 


{physical EOF of data fork) 


ioFlRStBlk: 


Integer ; 


{first alloc, blk. of resource fork} 


ioFlRLgLen: 


Longint ; 


{logical EOF of resource fork} 


ioFlRPyLen: 


Longint ; 


{physical EOF of resource fork) 


ioFlCrDat : 


Longint ; 


{date and time of creation} 


ioFlMdDat : 


Longint ; 


{date and time of last modification} 


ioFlBkDat : 


Longint ; 


{date and time of last backup} 


ioFlXFndrlnfo: 


FXInfo; 


{additional Finder information} 


ioFlParlD: 


Longint ; 


{file parent directory ID} 


ioFlClpSiz: 


Longint) ; 


{file's clump size) 



dirlnfo: 

(ioDrUsrWds : 
ioDrDirlD: 
ioDrNmFls: 
filler3: 
ioDrCrDat : 
ioDrMdDat : 
ioDrBkDat : 
ioDrFndrlnfo : 
ioDrParlD: 

END; 



DInfo; {information used by the Finder} 

Longint; {directory ID} 

Integer; {number of files in directory} 
ARRAY[l-.9] OF Integer; 

Longint; {date and time of creation) 

Longint; {date and time of last modification} 

Longint; {date and time of last backup} 

DXInfo; {additional Finder information} 

Longint); {directory's parent directory ID) 



The first 14 fields are common to both variants. Each variant also includes its own 
uruque fields. 

Field descriptions common to both variants 



qLink 

qType 
ioTrap 

ioCmdAddr 

ioCompletion 



ioResult 



A pointer to the next entry in the file I/O queue. (This field is used 
internally by the File Manager to keep track of asynchronous calls 
awaiting execution.) 

The queue type. (This field is used internally by the File Manager.) 

The trap number of the routine that was called. (This field is used 
internally by the File Manager.) 

The address of the routine that was called. (This field is used 
internally by the File Manager.) 

A pointer to a completion routine to be executed at the end of an 
asynchronous call. It should be NIL for asynchronous calls with no 
completion routine and is automatically set to NIL for all 
synduronous calls. See "Completion Routines" on page 2-238 for 
information about completion routines. 

The result code of the function. For synchronous calls, this field is 
the same as the result code of the function call itself. To determine 
when an asynchronous call has actually been completed, your 
application can poll this field; it's set to a positive number when 
the call is made and receives the actual result code when the call 
is completed. 
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ioNamePtr 



ioVRefNum 



ioFRefNum 
ioFVersNum 

fillerl 
ioFDirlndex 



ioFlAttrib 



A pointer to a pathname. Whenever a routine descripHon specifies 
that ioNamePtr is used— whether for input, output, or both— 
it's very important that you set this field to point to storage for a 
St r2 5 5 value (if you're using a pathname) or to NIL (if you're not). 
A volume specification. You can specify a volume using a volume 
reference number, a drive number, a working directory reference 
number, or 0 for the default drive. 
The file reference number of an open file. 

A file version number. This field is no longer used and you should 

always set it to 0. 

Reserved. 

A file and directory index. If this field contains a positive number, 
PBGetCatInf o returm information about the file or directory 
having that directory index in the directory specified by the 
ioVRefNum field. (If ioVRefNum contains a volume reference 
number, the specified directory is that volume's root directory.) 
If this field contair\s 0, PBGetCatInf o returns information about 
the file or directory whose name is specified in the ioNamePtr field 
and that is located in the directory specified by the ioVRefNum 
field. (Once again, if ioVRefNum contains a volume reference 
number, the specified directory is that volume's root directory.) 
If this field contains a negative number, PBGetCatInf o ignores the 
ioNamePtr field and returns information about the directory 
specified in the ioDirlD field. If both ioDirlD and ioVRefNum 
are set to 0, PBGetCatInf o retiuns information about the current 
default directory. 

File or directory attributes. For files, the bits in this field have the 
follovdng mearungs: 



Bit 


Meaning 


0 


Set if file is locked 


1 


Reserved 


2 


Set if resource fork is open 


3 


Set if data fork is open 


4 


Set if a directory 




Reserved 


7 


Set if file (either fork) is open 



For directories, the bits in this field have the following meanings: 
Bit Meaning 

0 Set if the directory is locked 

1 Reserved 

2 Set if the directory is within a shared area of the 
directory hierarchy 

3 Set if the directory is a share point that is mounted by 
some user 
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ioACUser 



Bit Meaning 

4 Set if the item is a directory 

5 Set if the directory is a share poir\t 
6-7 Reserved 

The user's access rights for the specified directory. The bits in this 
field have the following meanings: 

Bit Meaning 

0 Set if user does not have See Folder privileges 

1 Set if user does not have See Files privileges 

2 Set if user does not have Make Changes privileges 
3-6 Reserved; always set to 0 

7 Set if user is not owner of the directory 

For example, if you call PBGetCatInf o for a particular shared 
volume and ioACUser returns 0, you know that the user is the 
owner of the directory and has complete privileges to it. 



Field descriptions for the hFiieXnCo variant 



ioFlFndrlnf o 
ioDirlD 



ioFlStBlk 

ioFlLgLen 

ioFlPyLen 

ioFlRStBlk 

ioFlRLgLen 

ioFlRPyLen 

ioFlCrDat 

loFlMdDat 

ioFlBkDat 

ioFlXFndrlnfo 



ioFlParlD 
ioFlClpSiz 



Information used by the Finder. 

A directory ID or file ID. On input to PBGetCatInf o, this field 
contains a directory ID (which is used only if the ioFDir Index 
field is negative). On output, this field contains the file ID of the 
specified file. 

The first allocation block of the data fork. This field contair\s 0 if the 
file's data fork is empty. 

The logical end-of-file of the data fork. 

The physical end-of-file of the data fork. 

The first allocation block of the resource fork. 

The logical end-of-file of the resource fork. 

The physical end-of-file of the resource fork. 

The date and time of the file's creation, specified in seconds since 
midnight, January 1, 1904. 

The date and time of the last modification to the file, specified in 
seconds since midnight, January 1, 1904. 

The date and time of the last backup to the file, specified in seconds 
since midrught, January 1, 1904. 

Additional information used by the Finder. (See the chapter 
"Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials 
for details.) 

The directory ID of the file's parent. 

The clump size to be used when writing the file; if it's 0, the 
volume's clump size is used when the file is opened. 



I 



to 

3 
CD 
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Field descriptions for 

ioDrUsrWds 
ioDrDirlD 



ioDrNmFls 

fillers 

ioDrCrDat 



ioDrMdDat 



ioDrBkDat 



ioDrFndrlnfo 
ioDrParlD 



the dirinf o variant 
Information used by the Finder. 

A directory ID. On input to PBGetCatXnf o, this field contains a 

directory ID (which is used only if the value of the ioFDirlndex 

Held is negative). On output, this field contains the directory ID of 

the specified directory. 

The number of files in the directory. 

Reserved, 

The date and time of the directory's creafion, specified in seconds 
since midrught, January 1, 1904. 

The date and time of the last modification to the directory, specified 

in seconds since midnight, January 1, 1904. 

The date and time of the last backup to the directory, specified in 

seconds since midnight, January 1, 1904. 

Additional information used by the Finder. 

The directory ID of the specified directory's parent. 



Catalog Position Records 



When you call the PBCatSearch function to search a volume's catalog file, you can 
specify (in die ioCatPosition field of the parameter block passed to PBCatSearch) a 
catalog position record. If a catalog search consumes more time than is allowed by the 
ioSear chTime field, PBCatSearch stores a directory-location index in that record; 
when you call PBCatSearch again, it uses that record to resume searching where it left 
off. A catalog position record is defined by the CatPositionRec data type. 

TYPE CatPositionRec = (catalog position record) 
RECORD 

initialize: Longint; {starting point) 

priv: ARRAY[1..6] OF Integer; {private data) 

END; 



Field descriptions 

initialize 



priv 



The starting point of the catalog search. To start searching at 
the beginniiig of a catalog, specify 0 in this field. To resume a 
previous seardi, pass the value returned by the previous caU 
to PBCatSearch. 

An array of integers that is used internally by PBCatSearch. 



Catalog Move Parameter Blocks 



The low-level HFS function PBCatMove uses the catalog move parameter block defined 
by the CMovePBRec data type. 
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TYPE CMovePBRec 

RECORD 
qLink: 
qType : 
ioTrap: 
ioCmdAddr : 
ioCompletion: 
ioResult : 
ioNamePtr : 
ioVRefNum: 
f illerl : 
ioNewName : 
filler2: 
ioNewDirlD: 
filler3t 
ioDirlD: 

END; 



Field descriptions 

qLink 



qType 
ioTrap 

ioCmdAddr 

ioCompletion 



ioResult 



ioNamePtr 

ioVRefNum 
fillerl 



{catalog move parameter block} 

QElemPtr; {next queue entry} 

Integer; {queue type} 

Integer; {routine trap} 

Ptr; {routine address} 

ProcPtr; {pointer to completion routine} 

OSErr; {result code} 

StringPtr; {pointer to pathname} 

Integer; {volume specification} 

Longint; {reserved} 

StringPtr; {name of new directory} 

Longint; {reserved} 

Longint; {directory ID of new directory} 

ARRAY [1.. 2] OF Longint; {reserved} 

Longint; {directory ID of current directory} 



A pointer to the next entry in the file I/O queue. (This field is used 
iiitemally by the File Manager to keep track of asynchronous calls 
awaiting execution.) 

The queue type. (This field is used internally by the File Manager) 
The trap number of the routine that was called. (This field is used 
internally by the File Manager.) 

The address of the routine that was called. (This field is used 
internally by the File Manager.) 

A poiiiter to a completion routine to be executed at the end of an 
asynchronous call. It should be NIL for asynchronous calls with r\o 
completion routine and is automatically set to NIL for all 
synchronous calls. See "Completion Routines" on page 2-238 for 
information about completion routines. 

The result code of the function. For synchronous calls, this field is the 
same as the result cotje of the funcjdpn call its<^lf. To determine when 
an asynchronous call has actually been completed, your application 
can poll this field; if s set to a positive number when the call is made 
and receives the actual result code when the call is completed. 
A pointer to a pathriame. Whenever a routine description specifies 
that ioNamePtr is used — whether for input, output, or both — it's 
very important that you set this field to point to storage for a Str255 
value (if you're using a pathname) or to NIL (if you're not). 
A volume specification (volume reference number, working directory 
reference number, drive ntunber, or 0 for default volume). 
Reserved. 
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ioNewName The name of the directory into which the specified file or directory 

is to be moved. 
filler2 Reserved. 

ioNewDirlD The directory ID of the directory into which the specified file or 

directory is to be moved. 
filler3 Reserved. 

ioDi r ID The current directory ID of the file or directory to be moved (used 

in conjunction with the ioVRefWumand ioNamePtr fields). 



Working Directory Parameter Blocks 



The low-level HFS functions PBOpenWD, PBCloseWD, and PBGetWDInf o use the 
working directory parameter block defined by the WDPBRec data type. 



TYPE WDPBRec 
RECORD 



(working directory parameter block} 



qLink : 


QElemPtr ; 


{next queue entry} 




qType : 


Integers- 


{queue type} 




ioTrap: 


Integer; 


{routine trap) 




ioCmdAddr : 


Ptr; 


{routine address} 




ioCompletion: 


ProcPtr ; 


{pointer to completion routine} 




ioResult: 


OSErr; 


(result code} 




ioNamePtr : 


StringPtr; 


{pointer to pathname} 




ioVRefNum: 


Integer; 


(volume specification} 




f illerl: 


Integer; 


(reserved} 




ioWDIndex: 


Integer; 


(working directory index} 




ioWDProcID: 


Long In t ; 


(working directory user identifier} 


ioWDVRefNum: 


Integer; 


(working directory's vol. ref. 


num. } 


filler2: 


ARRAY[1. .7] 


OF Integer; (reserved) 




ioWDDirlD: 


Longint ; 


(working directory's directory 


ID) 



END; 



Field descriptions 

qLink 



qType 
ioTrap 

ioCmdAddr 

ioCompletion 



A pointer to the next entry in the file I/O queue. (This field is used 
internally by the File Manager to keep track of asynchronous calls 
awaiting execution.) 

The queue type. (This field is used internally by the File Manager.) 
The trap number of the routine that was called. (This field is used 
internally by the File Manager.) 

The address of the routine that was called. (This field is used 
internally by the File Manager.) 

A pointer to a completion routine to be executed at the end of an 
asynchronous call. It should be NIL for asynchronous calls with 
no completion routine and is automatically set to NIL for all 
synchronous calls. See "Completion Routines" on page 2-238 for 
information about completion routines. 
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ioResult 



ioNamePtr 



ioVRefNum 

fillerl 

ioWDIndex 

ioWDProcID 



ioWDVRefNum 

filler2 

ioWDDirlD 



The result code of the function. For synchronous calls, this field is 
the same as the result code of the function call itself. To determine 
when an asynchronous call has actually been completed, your 
application can poll this field; it's set to a positive number when 
the call is made and receives the actual result code when the call 
is completed. 

A pointer to a pathname. Whenever a routine description specifies 
that ioNamePt r is used — whether for input, output, or both — 
it's very important that you set this field to point to storage for a 
Str255 value (if you're using a pathname) or to NIL (if you're not). 
A volume specification (volume reference number, working 
directory reference ntimber, drive number, or 0 for default volume). 
Reserved. 

An index for use with the PBGetWDInf p function. 
An identifier that's used to distinguish between working directories 
set up by different users; you should set ioWDProcID to your 
application's signature. 

The working directory's volume reference number. 
Reserved. 

The working directory's directory ID. 



File Control Block Paranneter Blocks 



The low-level HFS function PBGetFCBInf o uses the file control block parameter block 
defined by the FCBPBRec data type. 



TYPE FCBPBRec 
RECORD 



{file control block parameter block) 



qLink: 


QElemPtr; 


{next queue entry} 


qType: 


Integer ; 


{queue type} 


ioTrap : 


Integer; 


{routine trap} 


ioCmdAddr : 


Ptr; 


{routine address) 


ioCompletion: 


ProcPtr; 


{pointer to completion routine} 


ioResult : 


OSErr; 


{result code} 


ioNamePtr : 


StririgPtr; 


{pointer to pathname} 


ioVRefNvun: 


Integer; 


{volume specification) 


ioRefNum: 


integers- 


{file reference number}. 


filler: 


Integer; 


{reserved} 


ioFCBIndx: 


Integer; 


{FCB index} 


fillerl: 


Integer; 


{reserved} 


ioFCBFlNm: 


Longint ; 


{file ID} 


ioFCBFlags : 


Integer; 


{flags} 


ioFCBStBlk: 


Integer; 


{first allocation block of file} 


ioFCBEOF: 


Longint ; 


{logical end-of-file} 


ioFCBPLen: 


Longint; 


{physical end-of-file). 
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ioFCBCrPs: Longint; 

ioFCBVRefNum: Integer; 

ioFCBClpSiz : Longint ; 

ioFCBPar ID : Longint ; 
END; 



{position of the file mark} 
{volume reference number) 
{file*s clump size) 
{parent directory ID) 



Field descriptions 

qLink 



qType 
ioTrap 

ioCmdAddr 

ioCompletion 



ioResult 



ioNamePtr 



ioVRefNum 

ioRef Num 

filler 

ioFCBIndx 

fillerl 

ioFCBFlNm 

ioFGBFlags 



A pointer to the next entry in the file I/O queue. (This field is used 
internally by the File Manager to keep track of asynchronous calls 
awaiting execution.) 

The queue type. (This field is used internally by the FQe Manager.) 
The trap number of the routine that was called. (This field is used 
internally by the File Manager.) 

The address of the routine that was called. (This field is used 
internally by the File Manager.) 

A pointer to a completion routine to be executed at the end of an 
asynchronous call. It should be NIL for asynchronous calls with 
no completion routine and is automahcally set to NIL for all 
synchronous calls. See "Completion Routines" on page 2-238 for 
information about completion routines. 

The result code of the fimction. For synchronous calls, this field is 
the same as the result code of the function call itself. To determine 
when an asynchronous call has actually been completed, yoiu: 
application can poll this field; it's set to a positive number when 
the call is made and receives the actual result code when the call 
is completed. 

A pointer to a pathname. Whenever a routine description specifies 
that ioNamePt r is used— whether for input, output, or both— 
it's very important that you set this field to point to storage for a 
Str255 value (if you're using a pathname) or to NIL (if you're not). 
A volume specification (volume reference number, working 
directory reference number, drive number, or 0 for default volume). 
The file reference number of an open file- 
Reserved. 

An index for use with the PBGetFCBInf o function. 

Reserved. 

The file ID. 

Flags describing the status of the file. The bits in this field that are 
currently used have the following meanings: 

Bit Meaning 

8 Set if data can be written to the file 

9 Set if this FCB describes a resource fork 

10 Set if the file has a locked byte range 

11 Reserved 
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ioFCBStBlk 

ioFCBEOF 

ioFCBPLen 

ioFCBCrPs 

ioFCBVRefNum 

ioFCBClpSiz 

ioFCBParlD 



Bit Meaning 

12 Set if the file has shared write permissions 

13 Set if the file is locked (write-protected) 

14 Set if the file's clump size is specified in the FCB 

15 Set if the file has changed since it was last flushed 
The number of the first allocation block of the file. 

The logical end-of-file. 

The physical end-of-file. 

The position of the file mark. 

The volume reference number. 

The file clump size. 

The file's parent directory ID. 



Volume Attributes Buffer 



The low-level HPS function PBHGetVol Farms returns information in the volume 
attributes buffer, defined by the GetVolParmsInf oBuf f er data type. 

TYPE GetVolParmsInfoBuffer = ' ' 

RECORD 

vMVersion: Integer; 

vMAttrib: Longint; 

vMLocalHand : Handle ; 

vMServerAdr: Longint; 

vMVolumeGrade : Longint; 

vMForeignPrivID: Integer; 
END; 



{version number) 
{volume attributes] 
{reserved) 

{network server address) 
{relative speed rating) 
{foreign privilege model) 



Field descriptions 

vMVersion 

vMAttrib 



vMLocalHand 



vMServerAdr 



The version of the attributes buffer structure. Currently this field 
returns either 1 or 2. 

A 32-bit quantity that encodes information about the volume 
attributes. See the )ist of cbmtante 

PBHGetVolPanhs beginning on page 2-147 for details on the 
meaning of each bit. 

A handle to private data for shared volumes. On creation of the 
VCB (right after mounting)^ this field is a handle to a 2-by te block 
of memory. The Finder uses this for its local window list storage, 
allocating and deallocating memory as needed. It is disposed of 
when the volume is unmounted. Your application should treat this 
field as reserved. 

For AppleTalk server volumes, this field contains the internet 
address of an AppleTalk server volume. Your application can 
inspect this field to tell which volumes belong to which server; the 
value of this field is 0 if the volume does not have a server. 
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vMVolumeGrade The relative speed rating of the volume. The scale used to 

determine these values is currently vincalibrated. In general, 
lower values iiidicate faster speeds. A value of 0 indicates that 
the volume's speed is uiuraled. The buffer version returned in 
the vMVersion field must be greater than 1 for this field to 
be meaningful. 

vMFore ignPr ivID 

An integer representing the privilege model supported by the 
volume. Currently two values are defined for this field: 
0 represents a standard HPS volume that might or might not 
support the AFP privilege model; f sUnixPr iv represents a 
volume that supports the A/UX privilege model. The buffer 
version returned in the vMVersion field must be greater than 1 
for this field to be meaiungful. 

Voltune Mounting Information Records 

The File Manager remote mounting functions store the mounting information in a 
variable-sized structure called a volume mounting information record, defined by the 
VolMountInf oHeader data type, 

TYPE VolMountInf oHeader = {volume mounting information} 

RECORD 

length: Integer; {length of mounting information} 

media: VolumeType; {type of volume} 

{volume-specific, variable-length location data} 
END; 

Field descriptions 

length The length of the VolMountInf oHeader structure (that is, 

the total length of the structure header described here plus the 
variable-length location data). The length of the record is flexible 
so that non-Macintosh file systems can store whatever information 
they need for volume mounting. 

media Tlie volume type of tiie remote volume. The value 

AppleShareMediaType (a constant that translates to • af pm ' ) 
represents an AppleShare volimie. If you are adding support for 
the programmatic mounting functions to a non-Madntosh file 
system, you should register a four-character identifier for your 
volumes with Macintosh Developer Technical Support at Apple 
Computer, Inc. 

The only volumes that currently support the programmatic mounting functions are 
AppleShare servers, which use a volume mounting record of type AFPVolMountInf o. 

TYPE AFPVolMountlnfo = {AFP volume mounting information) 
RECORD 

length; Integer; {length of mounting information} 

media: VolumeType; {type of volume} 
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f 1 aof s : 


Integer 




iii-'i-'J.iiLtiX Vd JL . 


SignedByte; 




SignedByte; 


uamType : 


Integer 




zoneNameOf f set ; 


Integer 




s er verNameO f f s e t 


: Integer 




volNameOf f set : 


Integer 




userNameOf f set : 


Integer 




userPasswordOf f s 


et : 






Integer; 



{reserved; must be set to 0} 
{NBP retry interval) 
{NBP retry count} 
(user authentication method) 
{offset to zone name) 
{offset server name) 
{offset to volume name) 
{offset to. user name) 

{offset to user password) 
volPasswordOf f set : 

Integer; {offset to volume password) 
AFPData: PACKED ARRAY [1 . .144] OF CHAR; 

{standard AFP mounting info) 
(optional volume-specific, variable-length data) 

END; 

Field descriptions 

l^^^th The length of the AFPVolMountInf o structure (that is, the total 

length of the structure header described here plus the variable- 
length location data). 

The volume type of the remote volume. The value 
AppleShareMediaType (a constant that translates to ' af pm ' ) 
represents an AppleShare volume. 

Reserved; set this field to 0. If bit 0 is set, no greeting message from 
the server is displayed. 

The NBP retransmit interval, in units of 8 ticks. 
The NBP retransmit covmt. This field spedJKes the total number of 
times a packet should be transmitted, including the first 
transmission. 

The access-control method used by the remote volume. AppleShare 
uses four methods, defined by constants: 



media 



flags 

nbplnterval 
npbCount 



uamType 



CONST 

kNoUserAuthentication - 1 

kPas sword = 2 

kEncryptPassword = 3 



{no password) 
{8-byte password} 



{encrypted 8-byte pasisword) 
kTwoWayEncryptPassword = 6; 

{two-way random encryption) 

zoneNaineOf f set The offset in bytes from the begiiming of the record to the entry in 
the AFPData field contairung the name of the AppleShare zone. 

serverNameOf f set 

The offset in bytes from the beginning of the record to the entry in 
the AFPData field containing the name of the AppleShare server 
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volNameOf f set The offset in bytes from the beginning of the record to the entry in 
the AFPData field containing the name of the volume. 

userNameOf f set The offset in bytes from the beginning of the record to the entry in 
the AFPData field containing the name of the user. 

userPasswordOf f set 

The offset in bytes from the begiiming of the record to the entry in 
the AFPData field containing the user's password. 

volPasswordOf f set 

The offset in bytes from the beginning of the record to the entry 
in the AFPData field containing the volume's password. Some 
versions of the AppleShare software do not pass the information 
in this field to the server. 

AFPData The actual volume mounting information, offsets to which are 

contained in the preceding sbc fields. To mount an AFP volume, you 
must fill in the record with at least the zone name, server name, 
user name, user password, and volume password. You can lay out 
the data in any order within this data field, as long as you specify 
the correct offsets in the offset fields. 



High-Level File Access Routines 

This section describes the File Manager's high-level file access routines. When you call 
one of these routines, you specify a file by a file reference number (which the File 
Manager returr\s to your application when the application opens a file). UrJess your 
application has very specialized needs, you should be able to manage all file access (for 
example, wrifing data to the file) using the routines described in this secfion. Typically 
you use these routines to operate on a file's data fork, but in certain circumstances you 
might want to use them on a file's resource fork as well. 

Reading, Writing, and Closing Files 

You can use the functions FSRead, FSWr i te, and FSClose to read data from a 
file, write data to a file, and close an open file. All three of these functions operate 
on opan files. You can use any one of a variety of routines to open a file (for example, 
FSpOpenDF). 



. FSRead 



You can use the FSRead function to read any number of bytes from an open file. 

FUNCTION FSRead (refNum: Integer; VAR count: Longlnt; 
buf fPtr: Ptr) : OSErr; 

re f Num The file reference number of an open file. 



2-112 File Manager Reference 



TlVO-408562 



CHAPTER 2 



File Manager 

count On input, the number of bytes to read; on output, the number of bytes 

actually read. 

bu f f Pt r A pointer to the data buffer into which the bytes are to be read. 

DESCRIPTION 

The FSRead function attempts to read the requested number of bytes from the specified 
file into the specified buffer The buf f Ptr parameter points to that buffer; this buffer is 
allocated by your application and must be at least as large as the count parameter. 

Because the read operation begins at the current mark, you might want to set the mark 
first by calling the SetFPos function. If you try to read past the logical end-of-file, 
FSRead reads in all the data up to the end-of-file, moves the mark to the end-of-file, and 
returns eof Err as its function result. Otherwise, FSRead moves the file mark to the byte 
following the last byte read and returns noErr. 

Note 

The low-level PBRead function lets you set the mark without having to 
call SetFPos. Also, if you want to read data in newline mode, you must 
use PBRead instead of FSRead. ♦ 



RESULT CODES 



noErr 


0 


No error 


ioErr 


-36 


I/O error 


fnOpnErr 


-38 


File not open 


eof Err 


-39 


Logical end-of-file reached 


posErr 


-40 


Attempt to position mark before start of file 


f LckdErr 


-45 


File is locked 


paramErr 


-50 


Negative count 


rfNumErr 


-51 


Bad reference number 


af pAccessDenied 


-5000 


User does not have the correct access to the file 



FSWrite 



You can use the FSWrite function to write any number of bytes to an open file. 

FUNCTION FSWrite (refNum: Integer; VAR count: Longint; 
buff Ptr: Ptr): OSErr; 

refNum The file reference number of an open file. 

count On input, the number of bytes to write to the file; on output, the nimiber 

of bytes actually written. 

bu f f Ft r A pointer to the data buffer from which the bytes are to be written. 
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DESCRIPTION 

The FSWri te function takes the specified number of bytes from the specified data buffer 
and attempts to write them to the specified file. Because the write operation begins at 
the current mark, you might want to set the mark first by calling the SetFPos function. 

If the write operation completes successfully, FSWri te moves the file mark to the 
byte foUowing the last byte written and returns noErr. If you try to write past the 
logical end-of-file, FSWri te moves the logical end-of-file. If you try to write past 
the physical end-of-file, FSWri te adds one or more clumps to the file and moves the 
physical end-of-file accordingly 

Note 

The low-level PBWr ite function lets you set the mark without having to 
call SetFPos. ♦ 



RESULT CODES 



noErr 


0 


No error 


dskFulErr 


-34 


Disk full 


ioErr 


-36 


I/O error 


f nOpnErr 


-38 


File not open 


posErr 


-40 


Attempt to position mark before start of file 


wPrErr 


-44 


Hardware volume lock 


fLckdErr 


^5 


Hie is locked . 


vliCkdErr 


-AS 


Software volume lock 


paramErr 


-50 


Negative count 


rfNumErr 


-51 


Bad reference number 


wrPermErr 


-61 


Read /write permission doesn't allow writing 



FSClose 



You can use the FSClose function to close an open file. 
FUNCTION FSClose (refNum: Integer) : OSErr; 
r ef Num The file reference number of an open file. 

DESCRimON 

The FSClose function removes the access path for the specified file and writes the 
contents of the volume buffer to the volume- 
Note 

The FSClose function calls PBFlushFile internally to write the file's 
bytes onto the volume. To ei\sure that the file's catalog entry is updated, 
you should call FlushVol after you call FSClose. ♦ 
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▲ VVARNtNG 

Make sure that you do not call FSClose with a file reference number of 
a file that has already been closed. Attempting to close the same file 
twice may result in loss of data on a volume. See "File Control Blocks" 
on page 2-81 for a description of how this can happen. ▲ 

RESULT CODES 

noErr 
ioErr 
fnOpnErr 
fnf Err 
rfNumErr 

Manipulating the File Mark ^ 

You can use the functions GetFPos and SetFPos to get or set the current position of the 
file mark. 



0 No error 

-36 I/O error 

-38 File not open 

-43 File not found 

-51 Bad reference number 



I 



(Q 
(D 



GetFPos 



You can use the GetFPos function to determine the current position of the mark before 
reading from or writing to an open file. 

FUNCTION GetFPos (refNum: Integer; VAR filePos: Longint) : OSErr; 

re f Num The file reference number of an open file. 
f i lePos On output, the current position of the mark. 

DESCRIPTION 

The GetFPos function returns. In the f ilePos parameter, the current position of the file 
mark for the specified open file. The position value is zero-based; that is, the value of 
f ilePos is 0 if the file mark is positioned at the beginning of the file. 

RESULT CODES 

noErr 0 No error 

ioErr -36 I/O error 

fnOpnErr -38 File not open 

rfNumErr -51 Bad reference nimiber 

gfpErr -52 Error during GetFPos 
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SetFPos 



You can use the SetFPos function to set the position of the file mark before reading 
from or writing to an open file. 

FUNCTION SetFPos (refNum: Integer; posMode: Integer; 

posOff: Longint): OSErr; 

ref Num The file reference number of an open file. 
posMode The positioning mode. 
posOf f The positioning offset. 



DESCRIPTION 



The SetFPos function sets the file mark of the specified file. The posMode parameter 
indicates how to position the mark; it must contain one of the following values: 



CONST 

fsAtMark = 0 

fsFromStart = 1 

fsFromLEOF = 2 

fsFromMark = 3 



{at current mark) 

{set mark relative to beginning of file} 

{set mark relative to logical end-of-file) 

{set mark relative to current mark} 



If you specify fsAtMark, the mark is left wherever it's currently positioned, and the 
posOf f parameter is ignored. The next three constants let you position the mark relative 
to either the beginning of the file, the logical end-of-file, or the current mark. If you 
specify one of these three constants, you must also pass in posOf f a byte offset (either 
positive or negative) from the specified point. If you specify f sFromLEOF, the value in 
posOf f must be less than or equal to 0. 



RESULT CODES 



no Err 

ioErr 

fnGpiiErr 

eofErr 

posErr 

rfNumErr 



0 No error 

-36 I/O error 

-38 File not open 

-39 Logical end-of-file reached 

-40 Attempt to position mark before start of file 

-51 Bad reference number 



Manipulating the End-of-File 



You can use the functions GetEOF cmd SetEOF to get or set the logical end-of-file of an 
open file. 
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GetEOF 



You can use the GetEOF function to determine the current logical end-of-file of an 
open file. 

FUNCTION GetEOF (refNum: Integer; VAR logEOF: Longint) : OSErr; 

ref Num The file reference number of an open file. 
logEOF On output, the logical end-of-file. 

DESCRIPTION 

The GetEOF function retunr\s, in the logEOF parameter, the logical end-of-file of the 
specified file. 



RESULT CODES 



noErr 0 

ioErr -36 

fnOpnErr -38 

rfNumErr -51 

afpAccessDenied -5000 



No error 

I/O error 

File not open 

Bad reference number 

User does not have the correct access to the file 



SetEOF 



You can use the SetEOF function to set the logical end-of-file of an open file. 

FUNCTION SetEOF (refNum: Integer; logEOF: Longint): OSErr; 

refNum The file reference number of an open file. 
logEOF The logical end-of-file. 

DESCRIPTION 

The SetEOF function sets the logical end-of-file of the specified file. If you attempt to set 
the logical end-of-file beyond the physical end-of-file, ttie physical end-of-file is set 
1 byte beyond the end of the next free allocation block; if there isn't enough space on the 
volume, no change is made, and SetEOF returns dskFulErr as its function result. 

If you set the logEOF parameter to.O, aU space occupied by the file on the volimie is 
released. The file still exists, but it contains 0 bytes. Setting a file fork's end-of-file to 0 is 
therefore not the same as deleting the file (which removes both file forks at once). 
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RESULT CODES 



noErr 


0 


No error 


dskFulErr 


-34 


DiskfuU 


ioErr 


-36 


I/O error 


friOpnErr 


-38 


File not open 


wPrErr 


-A^ 


Hardware volume lock 


fLckdErr 


-45 


File is locked 


vLckdErr 


-46 


Software volume lock 


rfNumErr 


-51 


Bad reference number 


wrPerraErr 


-61 


Read/write permission doesn't allow writing 



Allocating File Blocks 

The File Manager provides two functions. Allocate and AllocContig, that aUow you 
to allocate additional blocks to a file. The File Manager automatically allocates file blocks 
if you move the logical end-of-file past the physical end-of-file, and it automatically 
deallocates unneeded blocks from a file if you move the logical end-of-file to a position 
more than one allocation block before the current physical end-of-file. Consequently 
you do not in general need to be concerned with allocating or deallocating file 
blocks. However, you can improve file block contiguity if you use the Allocate 
or Al locCont ig function to preallocate file blocks. This is mO'St uSefullf you know 
in advance how big a file is likely to become. 

Note 

When the File Manager allocates (or deallocates) file blocks 
automatically, it always adds (or removes) blocks in dumps. The 
Allocate and AllocContig functions allow you to add blocks 
in allocation blocks, which may be smaller than clumps. ♦ 

The Allocate and AllocContig functions are not supported by AppleShare volimies. 
Instead, use SetEOF or PBSetEOF to extend a file by setting the end-of-file. 



Allocate 



You can use the Al locate function to allocate additional blocks to an open file. 
FUNCTION Allocate (refNum: Integer; VAR count: Longint) : OSErr; 
re f Num The file reference number of an open file. 

count On input, the number of additional bytes to allocate to the file; on output, 

the niunber of bytes actually allocated, roimded up to the nearest 
multiple of the allocation block size. 

DESCRIPTION 

The Allocate function adds the specified number of bytes to the specified fOe and sets 
the physical end-of-file to 1 byte beyond the last block allocated, tt there isn't enough 
empty space on the volume to satisfy the allocation request, Al locate allocates the rest 
of the space on the volume and returns dskFulErr as its function result. 
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The Al locate function always attempts to allocate contiguous blocks. If the total 
number of requested bytes is unavailable, Al locate allocates whatever space, 
contiguous or not, is available. To force the allocation of the entire requested space as a 
contiguous piece, call AllocContig instead. 

RESULT CODES 



noErr 


0 


No error 


dskFulErr 


-34 


Disk hill 


ioErr 


-36 


I/O error 


fnOpnErr 


-38 


File not open 


wPrErr 


-44 


Hardware volume lock 


fLckdErr 


-A5 


File is locked 


vLckdErr 


-46 


Software volume lock 


rfNumErr 


-51 


Bad reference number 


wrPermErr 


-61 


Read /write permission doesn't allow writing 



AllocContig 

You can use the Al locCont ig function to allocate additional contiguous blocks to an 
open file. 

FUNCTION AllocContig (refNum: Integer; VAR count : Longint) : OSErr; 
ref Num The file reference number of an open file. 

count On input, the number of additional bytes to allocate to the file; on output, 

the number of bytes allocated, rounded up to the nearest multiple of the 
allocation block size. 



DESCRIPTION 

The AllocContig function is identical to the Allocate function except that if there 
isn't enough contiguous empty space on the volume to satisfy the allocation request, 
AllocContig does nothing and returns dskFulErr as its function result. If you want 
to allocate whatever space is available, even when die entire request cannot be filled by 
the allocation of a contiguous piece, call Allocate instead. 

RESULT CODES 



no^Irr 


0 


No error 


dskFulErr 


-34 


Diskfull 


ioErr 


-36 


I/O error 


fnOpnErr 


-38 


File not open 


wPrErr 


-44 


Hardware volume lock 


fLckdErr 


^5 


File is locked 


vLckdErr 


-46 


Software volume lock 


rfNumErr 


-51 


Bad reference number 


wrPermElrr 


-61 


Read /write permission doesn't allow writing 
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Low-Level File A ccess Routines 

This section describes the low-level file access routines. These low-level routines, whose 
names begin with the letters PB, provide two advantages over the corresponding 
high-level file access routines: 

■ These routines can be executed asynchronously, returrung control to your application 

before the operation is completed. 
H In certain cases, these routines provide more extensive information or perform 

advanced operations. 

All of these routines exchange parameters with your application through a parameter 
block of type ParamBlock. When you call a low-level routine, you pass the address of 
the parameter block to the routine. 

Assembly-Language Note 

When you call any of these low-level routines, register AO must point to 
a parameter block containing the parameters for the routine. If you want 
the routine to be executed asynchronously, set bit 10 of the routine trap 
word. You can do this by supplying the word ASYNC as the second 
argument to the routine macro. Here's an example: 

_Read, ASYNC 

You can set or test bit 10 of a trap word using the global constant 
asyncTrpBit. 

The hierarchical extensions of certain basic File Manager routines 
actually are not new calls. For instance, _Open and _HOpen both trap to 
the same routine. The trap word generated by the _HOpen macro is the 
same as the trap word that would be generated by invoking the _Open 
macro with bit 9 set. The setting of this bit tells the File Manager to 
expect a larger parameter block containing the additional fields (such as 
a directory ID) needed to handle a hierarchical directory volume. You 
can set or test bit 9 of a trap word by using the global constant hf sBit. 

All File Manager routines return a result code in register DO. ♦ 
These low-level file access routines can run either synchronously or asynchronously 
There are three versions of each routine. The first takes two parameters: a pointer to the 
parameter block and a Boolean parameter that specifies whether the routine is to run 
asynchronously (TRUE) or synchronously (FALSE). For example, the first version of the 
low-level routine to read bytes from a file has this declaration: 

FUNCTION PBRead (paraitiBlock: ParmBlkPtr; async: Boolean): OSErr; 

The second version does not take a second parameter; instead, it adds the suffix Async 
to the name of the routine. 

FUNCTION PBReadAsync (paramBlock: ParmBlkPtr) r OSErr; 
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Similarly, the third version of the routine does not take a second parameter; instead, it 
adds the suffix Sync to the name of the routine. 

FUNCTION PBReadSync (paramBlock: ParmBlkPtr) : OSErr; 

Only the first version of each routine is documented in this section. (See "Summary of 
the File Manager," begixming on page 2-240, for a listing of all three versions of these 
routines.) Note, however, that the second and third versions of these routines do not use 
the giue code that the first version uses and are therefore more efficient. 

Note 

Although you can execute low-level file access routines asynchronously, 
the tmderlying device driver may not suppoirt asynchronous operation. 
The SCSI Manager, for example, currently supports only synchronous 
data transfers. Data transfers to a floppy disk or to a network server, 
however, can be made asynchronously. ♦ 

Reading, Writing, and Closin g Files . 

You can use the functions PBRead, PBWrite, and PBClose to read data from a file, 
write data to a file, and close an open file. All three of these functions operate on open 
files. You can use any one of a variety of routines (for example, PBHOpenDF) ta open 
a file. 



PBRead 



You can use the PBRead function to read any number of bytes from an open file. 

FUNCTION PBRead (paramBlock: ParmBlkPtr; async: Boolean): OSErr; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 



(FALSE) execution. 



Parameter block 



-> 


ioCompletion 


PirocPtr 


<- 


ioResult 


OSErr 




ioRefNum 


Integer 


-> 


ioBuf f er 


Ptr 


-> 


ioReqCount 


Longint 


<- 


iOActCount 


Longint 




ioPosMode 


Integer 


<-> 


ioPosOffset 


Longint 



A pointer to a completion routine. 
The residt code of the function. 
A file reference number. 
A pointer to a data buffer. 
The number of bytes requested. 
The number of bytes actually read. 
The positioning mode. 
The positioning offset. 
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DESCRIPTION 

The PBRead function attempts to read ioReqCount bytes from the open file whose 
access path is speci^ed in the ioRef Num field and transfer them to the data buffer 
pointed to by the ioBuf f er field. The position of the mark is specified by ioPosMode 
and ioPosOf f set. If your application tries to read past the logical end-of-file, PBRead 
reads the data, moves the mark to the end-of-file, and returns eof Err as its function 
result Otherwise, PBRead moves the file mark to the byte following the last byte read 
and rehims noErr,. After the read is completed, the mark is returned in ioPosOf f set, 
and the number of bj'tes actually read into the buffer is rehimed in ioActCount. 

You can specify that PBRead read the file data 1 byte at a time until the requested 
number of bytes have been read or until the end-of-file is reached. To do so, set bit 7 of 
the ioPosMode field. Similarly, you can specify that PBRead should stop reading data 
when it reaches an application-defined newline character. To do so, place the ASCII code 
of that character into the high-order byte of the ioPosMode field; you must also set bit 7 
of that field to enable newline mode. 

Note 

When reading data in newline mode, PBRead returns the newline 
character as part of the data read and sets ioAct Count to the achjal 
number of bytes placed into d\e buffer (which includes the newline 
character). ♦ 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBRead is _Read. 



No error 
I/O error 
File not open 

Logical end-of-file reached 

Attempt to position mark before start of file 

File is locked 

Negative ioReqCount 

Bad reference number 

User does not have the correct access to the file 



PBWrite . 

You can use the PBWrite function to write any number of bytes to an open file. 
FUNCTION PBWrite (paramBlock: ParmBlkPtr; async : Boolean): OSErr; 
paramBlock A pointer to a basic File Manager parameter block. 



RESULT CODES 



noErr 


0 


ioErr 


-36 


fnOpnErr 


-38 


eofErr 


-39 


posErr 


-40 


fLckdErr 


-45 


paramErr 


-50 


rfNuniErr 


-51 


a f p Ac c es sDen i ed 


-5000 
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a sync A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<- 


ioResult 


OSErr 


The result code of the function. 


— > 


ioRefNum 


Integer 


A file reference number. 




ioBuf f er 


Ptr 


A pointer to a data buffer. 


-> 


■ ioReqCount 


Longint 


The number of bytes requested. 


<- 


ipActCount 


Longint 


The number of bytes actually written. 


— > 


ioPosMode 


Integer 


The positioning mode. 




ioPosOf f set 


Longint 


The positioning offset. 



DESCRIPTION 

The PBWrite function takes ioReqCount bytes from the buffer pointed to by 
ioBuf f er and attempts to write them to the open file whose access path is specified by 
ioRefNum. The position of the mark is specified by ioPosMode and ioPosOf f set. If 
the write operation completes successfully, PBWrite moves the file mark to the byte 
following the last byte written and returns noErr. After the write operation is 
completed, the mark is returned in ioPosOf f set and the number of bytes actually 
written is returned in icAct Count. 

If you try to write past the logical end-of-file, PBWrite moves the logical end-of-file. If 
you try to write past the physical end-of-file, PBWrite adds one or more dumps to the 
file and moves the physical end-of-file accordingly. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBWrite is __Write. 

RESULT CODES 



noErr 


0 


No error 


dskFulErr 


-34 


Disk full 


ioErr 


-36 


I/O error 


fnOpnErr 


-38 


File not open 


posErr 


-40 


Attaup t to position mark before start of file 


wPrErr 


-44 


Hardware voltone lock 


fLckdErr 


-45 


File is locked 


vLckdErr 


-46 


Software volimie lock 


paramErr 


-50 


Negative ioReqCoxmt 


rfNumErr 


-51 


Bad reference number 


wrPermErr 


-^1 


Read /write permission doesn't allow writing 
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PBClose 

You can use the PBClose function to close art open file. 

FUNCTION PBClose (paramBlock: ParmBlkPtr; async: Boolean): OSI 

paramBlock A pointer to a basic File Manager parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

A pointer to a completion routine. 
The result code of the function. 
A file reference number. 



Parameter block 

ioCompletion ProcPtr 

<r- ioResult OSErr 

-> ioRefNum Integer 



DESCRIPTION 



The PBClose function writes the contents of the access path buffer specified by the 
ioRefNum field to the volume and removes the access path. 

WARNING 

Some information stored on the volume won't be updated ^^^il^^^ 
PBFlushVol is called, a 

WARNING 

Do not call PBClose with a file reference number of a file that has 
already been closed. Attempting to close the same file twice may result 
in loss of data on a volume. See 'TUe Control Blocks" on page 2-81 for a 
description of how this can happen. A 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBClose is _Close. 



RESULT CODES 

noErr 0 No error 

ioErr -36 t/O error 

f nOpnErr -38 File not open 

fnfErr -43 File not found 

rfNumErr -51 Bad reference number 
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Manipulating the File Miark 



You can use the functions PBGetFPos and PBSetFPos to get or set the current position 
of the file mark. 



You can use the PBGetFPos function to determine the current position of the file mark 
before reading from or writing to an open file. 

FUNCTION PBGetFPos (paramBlock : ParmBlkPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<— 


ioResui t 


OSErr 


The result code of the function. 




ioRefNum 


Integer 


A file reference number. 


<r- 


ioReqCount 


Longlnt 


On output, set to 0. 


<~ 


ioActCount 


Longint 


On output, set to 0. 




ioPosMode 


Integer 


On output, set to 0. 




ioPosOf f set 


Longlnt 


The current position of the mark. 



The PBGetFPos function returns, in the ioPosOf f set field, the mark of the specified 
file. The value returned in ioPosOf f set is zero-based. Thus, a call to PBGetFPos 
returns 0 if you call it when the file mark is positioned at the beginning of the file. 



PBGetFPos 



DESCRIPTION 



ASSEMBLY-LANGUAGE INFORMATION 

Hie trap macro for PBGetFPos is 



GetFPos. 



RESULT CODES 



noErr 
ioErr 



f nOpnErr 
rfNumErr 
gfpErr 



0 

-36 
-38 
-51 
-52 



No error 

I/O error 

File not open 

Bad reference number 

Error during PBGetFPos 
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PBSetFPos 



You can use the PBSetFPos function to position the file mark before reading from or 
writing to an open file. 

FUNCTION PBSetFPos (paramBlock: ParmBlkPtr; async: Boolean): 

OSErr ; 

paramBlock A pointer to a basic File Manager parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 

ioCompletion ProcPtr 

<- ioResult OSErr 

ioRefWum Integer 

ioPosMode Integer 

^ ioPosOffset Longint 



A pointer to a completion routine. 

The result code of the function. 

A file reference number. 

The positioning mode. 

On input, the positioning offset. On 

output, the position at which the mark 

was actually set. 



DECRIPnON c J u 

The PBSetFPos hmction sets the mark of the specified file to the position specified by 
the ioPosMode and ioPosOf f set fields. If you try to set the mark past the logical 
end-of-file, PBSetFPos moves the mark to the end-of-file and returns eof Err as its 
function result. 



ASSEMBLY-lANGmCE INFQRMATION 

The trap macro for PBSetFPos is _SetFPos. 



RESULT CODES 



noErr 

ioErr 

fnOpnErr 

eafErr 

posErr 

rftlumErr 

extFSErr 



0 Noertor 

-36 r/6 error 

-38 File not open 

-39 Logical end-of-file reached 

-40 Attempt to position mark before start of file 

-51 Bad reference number 
-58 - External file system 



Mani pulating the End-of-File 

7ou can use the functions PBGetEOF and PBSetEOF to get or set the current end-of-file. 
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PBGetEOF 



You can use the PBGetEOF function to determine the current logical end-of-file of an 
open file. 

FUNCTION PBGetEOF (paramBlock : ParmBlkPtr; async: Boolean): OSErr; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE). or synchronous 

(FALSE) execution. 

Parameter block 

ioCompletion . ProcPtr A pointer to a completion routine. 

<r~ ioResult OSErr The result code of the function. 

-> ioRefNum Integer A file reference number. 

<r~ ioMisc Ptr The logical end-of-file. 



DESCRIPTION 

The PBGetEOF function returns, in the ioMisc field, the logical end-of-file of the 
specified file. Because ioMisc is of type Ptr, you'll need to coerce the value to type 
Longint to interpret the value correctly. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBGetEOF is _GetEOF. 



RESULT CODES 



noErr 0 

ioErr -36 

fnOpnErr -38 

rfNumErr -51 

a fpAc cess Denied -5000 



No error 

I/O error 

File not open 

Bad reference number 

User does not have the correct access to the file 



PBSetEQF 

You can use the PBSe tEOF function to set the logical end-of-file of an open file. 

FUNCTION PBSetEOF (paramBlock: PanaBlkPtr; async: Boolean): OSErr; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 
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Parameter block 

ioCompletion ProcPtr 

<- ioResult OSErr 

-> ioRefNmn Integer 

-4 ioMisc Ptr 



A pointer to a completion routine. 
The result code of the function. 
A file reference number 
The logical end-of-file. 



DESCRIPTION 

The PBSetEOF function sets the logical end-of-file of the open file, whose access path is 
specified by ioRef Num, to ioMisc. Because the ioMisc field is of type Ptr, you must 
coerce the desired value from type Longint to type Ptr. 

If you attempt to set the logical end-of-file beyond the current physical end-of-file, 
another allocation block is added to the file; if there isn't enough space on the volume, 
no change is made and PBSetEOF returns dskFul Err as its function result. 

If the value of the ioMisc field is 0, all space occupied by the file on the volume is 
released. The file still exists, but it contair^ 0 bytes. Setting a file fork's end-of-file to 0 
is therefore not the same as deleting the file (which removes both file forks at once). 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBSetEOF is _SetEOF. 



RESULT CODES 



noErr 


0 


No error 


dskFulErr 


-34 


Disk full 


ioErr 


-36 


I/O error 


fnOpnErr 


-38 


File not open 


wPrErr 


-44 


Hardware volume lock 


fLckdErr 


-45 


File is locked 


vLckdErr 


-AS 


Software volume lock 


rfNumErr 


-51 


Bad reference number 


wrPerraErr 


^1 


Read/ write permission doesn't allow writing 



AUocatmg File Blocks 

The File Manager provides two low-level functions, PBAllocate and PBAllocCont ig, 
that allow you to allocate additional blocks to a file. The File Manager automatically 
allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it 
automatically deallocates tmneeded blocks from a file if you move the logical end-of-file 
to a position more than one allocation block before the current physical end-of-file. 
Consequently, you do not in general need to be concerned with allocafing or deallocating 
file blocks. However, you can improve file block contiguity if you use the PBAllocate 
or PBAllocCont ig function to preallocate file blocks. This is most useful if you know in 
advance how big a file is likely to become. 

PBAllocate and PBAllocContig are not supported by AppleShare volumes. Instead, 
use SetEOF or PBSetEOF to extend a file by setting the end-of-file. 
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PBAllocate 



You can use the PBAllocate function to allocate additional blocks to an open file. 

FUNCTION PBAllocate (paramBlock: ParmBlkPtr? async: Boolean): 

OSErr; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(false) execution. 

Parameter block 

A pointer to a completion routine. 
The result code of the function. 
A file reference number. 
The number of bytes requested. 
The number of bytes actually 
allocated, rounded up to the nearest 
multiple of the allocation block size. 



— > 


ioCompletion 


ProcPtr 




ioResult 


OSErr 


-> 


ioRefNum 


Integer 


— > 


ioReqCount 


Long In t 




ioActCount 


Longint 



DESCRIPTION 

The PBAllocate function adds ioReqCount bytes to the specified fUe and sets the 
physical end-of-file to 1 byte beyond the last block allocated. If there isn't enough empty 
space on the volume to satisfy the allocation request, PBAllocate allocates the rest of 
the space on the volume and returns dskFulErr as its function result. 

Note 

If the total number of requested bytes is unavailable, PBAllocate 
allocates whatever space, contiguous or not, is available. To force the 
allocation of the entire requested space as a contiguous piece, call 
PBAllocContig instead. ♦ 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBAi locate is _A1 locate. 

RESULT CODES 



noErr 


0 


No error 


dskFulErr 


-34 


E>iskfuli 


ioErr 


-36 


I/O error 


fnOpnErr 


-38 


File not open 


wPrErr 


-44 


Hardware volume lock 


fLckdErr 


-45 


File is locked 


vLckdErr 


-46 


Softv/are volume lock 


rfNumErr 


-51 


Bad reference number 


wrPermErr 


^1 


Read /write permission doesn't allow v^riting 
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PBAUocContig 



You can use the PBAl locCont ig function to allocate additional contiguous blocks to an 
open file. 

FUNCTION PBAUocContig {paramBlock : PanuBlkPtr; async: Boolean): 

OSErr ; 

paramBlock A pointer to a basic FUe Manager parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 

ioCompletion ProcPtr 

ioResult OSErr 

ioRefNum Integer 

ioReqCount Longint 

ioActCount Longint 



— 3^ 



A pointer to a completion routine. 
The result code of the function. 
A file reference number. 
The number of bytes requested. 
The number of bytes allocated, 
rounded up to the nearest multiple 
of the allocation block size. 



DESCRIPTION 



The PBAUocContig hmction is identical to the PBAllocate hmction except that if 
there isn't enough contiguous empty space on the volume to satisfy tiie allocation 
request, PBAUocContig does nothing and returns dskFulErr as its hinction result. If 
you want to allocate whatever space is available, even when the entire request cannot be 
filled by the allocation of a contiguous piece, caU PBAllocate mstead. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBAUocContig is _AllocContig. 



RESULT CODES 



noflrr 


0 


dskFulErr 


-34 


ioErr 


-36 


fnOpnErr 


-38 


wPrErr 


-44 


fLckdErr 


-45 


vLckdErr 


-46 


rfNuiuErr 


-51 


wrPermErr 


-61 



No error 
Disk full 
I/O error 
File not open 
Hardware volume lock 
File is locked 
Software volume lock 
Bad reference number 

Read /write permission doesn't allow writing 
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You can use the PBFlushFile function to ensure that the path access buffer of a file is 
written to disk. There is no high-level equivalent of this function. 



PBnushFile 



You can use the PBFlushFile function to write the contents of a file's access path buffer. 

FUNCTION PBFlushFile (paramBlock : ParmBlkPtr; async: Boolean): 

OSErr ; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 

-> ioComplet ion ProcPtr A pointer to a completion routine. 

<- ioResult OSErr . The result code of the function. 

ioRefNum Integer A file reference number. 



DESCRIPTION 



The PBFlushFile function writes the contents of the access path buffer indicated by 
ioRefNum to the volume and then updates the file's entry in the volume catalog. 

A WARNING 

Some information stored on the volume v^^on't be correct until 
PBFlushVol is called, a 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBFlushFi le is _FlushFile. 



RESULT CODES 



noErr 0 No error 

nsvErr -35 Volume not foimd 

ioErr -36 I/O error 

f nOpnErr -38 File not open 

fnfErr -43 File not found 

r f NumEr r -51 Bad reference number 

extFSErr -58 External file system 
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High-Level Voltime Access Routines 



This s^tion describes the File Manager's high-level routines for accessing volumes. 
Most applications are likely to need only the FlushVol hmction described on 
page 2-134- 

When you caU one of these routines, you specify a volume by a volume reference 
number (which you can obtain, for example, by calling the GetVInf o function, or from 
the reply record returned by the Standard File Package). You can also specify a volume 
by name, but this is generally discouraged, because there is no guarantee that volume 
names will be imique. 



Unmounting Volumes 



The functions UnmountVol and E j ec t aUow you to unmount and eject volumes. Most 
applications do not need to use these routines, because the user typically ejects (and 
possibly also unmounts) a volume in the Finder. 



UnmountVol 



You can use the UnmountVol hmction to unmount a volume that isn't currentiy 
being used. 

FUNCTION UnmountVol (volName: StringPtr; vRefNum: Integer): OSErr; 
volName A pointer to the name of a mounted volume. 

VRefNum A volume reference number, a working directory reference number, a 
drive number, or 0 for the default volume. 



DESCRIPTION 



The UnmountVol function unmounts the specified volume. All files on the volume 
(except those opened by the Operating System) must be closed before you call 
UnmountVol, which does not eject the volume. 

WARNING 

Don't unmount the startup volume. Doing so will cause a 
system crash, a 
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RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad volume name 


fBsyErr 


-47 


One or more files are open 


paramErr 


-50 


No default volume 


nsDrvErr 


-56 


No such drive 


extFSErr 


-58 


External file system 



Eject 

You can use the E j ect function to place a volume offline and eject it. 

FUNCTION Eject (volName: StringPtr; vRefNum: Integer): OSErr; 

volNaine A pointer to the name of a volume. 

vRefNum A volume reference number, a working directory reference number, a 
drive number, or 0 for the default volume. 



DESCRIPTION 



The Eject function flushes the specified volume, places it offline, and then ejects 
the volume. 



RESULT CODES 



noErr 

nsvErr 

ioErr 

bdNamErr 

paramErr 

nsDrvErr 

extFSErr 



0 No error 

-35 No such volume 

-36 I/O error 

-37 Bad volume name 

-50 No default volume 

-56 No such drive 

-58 External file system 



Updating Volumes 

When you dose a file, you should call FlushVol to ensure that any changed contents of 
the file are written to the volvume. 
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FlushVol 



You can use the FlushVol function to write the contents of the volume buffer and 
update information about the volimie. 

FUNCTION FlushVol (volName: StringPtr; vRefNum: Integer): OSErr; 
volName A pointer to the name of a mounted volume. 

VRefNum A volume reference number, a working directory reference number, a 
drive number, or 0 for the default volume. 



PESCRirnoN , 
On the specified volume, the FlushVol hmction writes the contents of the associated 
volume buffer and descriptive information about the volume (if they've dianged smce 
the last time FlushVol was called). This information is written to the volume. 



RESULT CODES 



noErr 

nsvErr 

ioErr 

bdNamErr 

paramErr 

nsDrvErr 



0 No error 

-35 No such volimie 

-36 I/O error 

-37 Bad volume name 

-50 No default volume 

-56 No such drive 



Manipulating the Default Volume 



The hmctions GetVol, SetVol, HGetVol, and HSetVol allow you to determine which 
volume is the default volume and to set the default volume. 



GetVol 



You can use the GetVol hmction to determine the current default volume and possibly 
also the default directory. 

FUNCTION GetVol (volName: StringPtr; VAR vRefNum: Integer): OSErr; 
volName A pointer to the name of the default volume. 

vRe f Num A volume reference number or a working directory reference number. 
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The Getvol function returns a pointer to the nanie of the default volume in the volName 
parameter and its volume reference number in the vRef Num parameter. If the default 
directory has a working directory associated with it, the vRef Num parameter instead 
contams a working directory reference number (which encodes both the volume reference 
number and the default directory ID). However, if, in a previous call to HSet Vol (or 
PBHSetVol), a working directory reference number was passed in, GetVol returns a 
volume reference number in the vRefNum parameter. 



RESULT CODES 



noErr 
nsvErr 



0 No error 
-35 No such volume 



SetVol 



DESCRIPTION 



You can change the default volume and default directory using the SetVol funcHon. 
FUNCTION SetVol (volName: StringPtr; vRefNum: Integer): OSErr; 
volName A pointer to the name of a mounted volume. 

VRefNum A volume reference number or a working directory reference number. 



The SetVol function sets the default volume and directory to the values specified in the 
volName and vRef Num parameters. If you pass a volume reference number in vRef Num 
or a pomter to a volume name in volName, SetVol makes the specified volume the 
default volume and the root directory of that volume the default directory If you pass a 
working directory reference number in vRef Num, SetVol makes the specified directory 
the default directory, and the volume containing that directory the default volume 



RESULT-CODES 



noErr 
nsvErr 
bdNamErr 
paramErr 



0 No error 

-35 No such volume 

-37 Bad volume name 

-50 No default volume 
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HGetVol 



You can use the HGetVol function to determine the current default volume and 
default directory. 

FUNCTION HGetVol (volName: StringPtr; VAR vRefNum: Integer; 
VAR dirlD: Longint) :. OSErr; 

volName A pointer to the name of the default volume. 

vRef Num A volume reference number or a working directory reference number. 
dirlD The directory ID of the default directory. 



DESCRIPTION 



The HGetVol function returns the name and reference number of the default volume, as 
v^^ell as the directory ID of the default directory. A pointer to the name of the default 
volume is returned in the volName parameter, unless you set volName to NIL before 
calling HGetVol. 

The HGetVol function returns a v^orking directory reference number in the vRef Num 
parameter if the previous call to HSetVol (or PBHSetVol) passed in a working 
directory reference number. If, however, you have previously called HSetVol (or 
PBHSetVol) specifying the target volume with a volume reference number, then 
HGetVol returns a volume reference number in the vRef Num parameter. 



RESULT CODES 



noErr 0 No error ' 

nsvErr -35 No default volume 



HSetVol 



You can use the HSetVol function to set both the default volume and the default 
directory. 

FUNCTION HSetVol {volName: StringPtr; vRefNum: Integer; 
dirlD: LongInt) : OSErr; 

volName A pointer to the name of a moimted volume or the partial pathname 
of a directory. 

vRe f Num A volume reference number or a working directory reference number, 
di r I D A directory ID. 
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DESCRIPTION 



The HSetVol funcHon lets you specify the default directory by volume reference 
number by directory ID, or by a combination of working directory reference number 
and partial pathname (beginning from that working directory). 

A WARNING 

Use of the HSetVol function is discouraged if your application may 
execute m system software versions prior to version 7.0 Because the 
specified directory might not itself be a working directory, HSetVol 
records the default volume and directory, separately, using the volume 
reference number of the volume and the actual directory ID of the 
speafied directoiy. Subsequent calls to Get Vol (or PBGetVol) return 
only the volume reference number, which will cause that volume's root 
directory (rather than the default directory, as expected) to be accessed, a 

Note 

Both the default volume and the default directory are used in calls made 
with no volume name, a volume reference number of 0, and a directory 
ID or 0. ♦ ^ 



RESULT CODES 



noErr 

nsvErr 

bdNamErr 

fnf Err 

paramErr 

afpAccessDenied 



Obtaining Volume Information 



0 

-35 
-37 
-43 
-50 
-5000 



No error 
No such volume 
Bad volume name 
Directory not found 
No default volume 

User does not have access to the directory 



You can get information about a volume by calling the GetVInf o or 
Get VRefNum function. 



GetVInfo 



You can use the GetVInfo function to get information about a mounted volume. 



FUNCTION Get:VInfo (drvNum 



Integer; volName: StringPtr; 
VAR freeBytes: Longint) : OSErr; 



VAR VRefNum: Integer; 



drvNum IT.e drive number of the volume for which information is requested. 

volName On output, a pointer to the name of the specified volume. 

VRefNum The volume reference number of the specified volume. 

freeBytes The available space (in bytes) on the specified volume. 
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DESCRIPTION 

The Getvinf o function returns the name, volume reference number, and available 
space (in bytes) for the specified volume. You specify a volume by providing its dri^ 
number in the drvNum parameter. You can pass 0 in the drvNum parameter to get 
information about the default volume. 



RESULT CODES 

noErr 0 No error 

nsvErr -35 No such volimae 

paramErr -50 No default volume 



GetVRefNum 



You can use the GetVRefNum fimction to get a volume reference number from a file 
reference number 

FUNCTION GetVRefNum (refNum: Integer; VAR vRefNum: Integer): 

OSErr; 

refNum The file reference number of an open file. 

VRefNum On exit, the volume reference number of the volume containing the file 
specified by refNum. 



DESCRIPTION 

The Ge t VRe f Num function returns the volume reference number of the volume 
containing the specified file. If you also want to determine the directory ID of th 
specified file's parent directory, caU the PBGetFCBInf o function. 



RESULT CODES 

noErr 0 No error 

r f NumEr r -51 Bad reference number 



Low-Level Volu me Access Routines 

This section describes the low-level routines for accessing volumes. These routines 
exchange parameters with your application through a parameter block of type 
ParamBlock, HParamBlock, or WDPBRec. When you call a low-level routine, you 
pass the address of the appropriate parameter block to the routine. 
Some low-level routines for accessing volumes can run either asynchronously or 
synchronously. Each of these routines comes in three versions: one version requires t] 
async parameter and two have the suffix Async or Sync added to their names. For 
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more information about the differences between the three versions, see "Low-Level File 
Access Routines" on page 2-120. 

Or\ly the first version of these routines is documented in this section; See "Sununary of 
the File Manager/' beginning on page 2-240, for a listing that includes all three versions. 

Assembly-Language Note 

See the assembly-language note on page 2-120 for details on calling 
these routines from assembly language. ♦ 

Mounting and Unmounting Volumes 

The File Manager provides several low-level routines that allow you to mount and 
unmount Macintosh volumes, eject volumes, and place niounted volumes offline. 



PBMountVol 



You can use the PBMountVol function to mount a volume. 
FUNCTION PBMountVol (paramBlock: ParmBlkPtr) : OSErr; 
paramBlock A pointer to a basic FDe Manager parameter block. 
Parameter block 

<- ioResult OSErr The result code of the function. 

<r^ ioVRefNum Integer On input, a drive number. On output, 

the volume reference number. 

DESCRIPTION 

The PBMountVol function mounts the volume in the specified drive. If there are no 
volumes already mounted, this volume becomes the default volume. 

Because you specify the volume to be mounted by providing a drive number, you can 
use PBMountVol to moimt only one volume per disk. 

The PBMountVol fvmction always executes synchronously. 
Note 

The PBMountVol function opens two files needed for maintaining 
file catalog and file mapping information. If no access paths are 
available for these two files, PBMountVol fails and retun\s tmf oErr 
as its function result. ♦ 

*■ 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBMountVol is „MountVol. 
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RESULT CODES 



noErr 

ioErr 

tmfoErr 

paramErr 

volOnLinErr 

nsDrvErr 

noMacDskErr 

extFSErr 

badMDBErr 

mernFullErr 



0 


No error 


-36 


I/O error 


-42 


Too many files open 


-50 


Bad drive number 


-55 


Volume already online 


-56 


No such drive 


-57 


Not a Macintosh disk 


-58 


External file system 


-60 


Bad master directory block 


-108 


Not enough room in heap zone 



PBUnmountVol 



You can use the PBUnmountVol hmction to unmount a volume. 
FUNCTION PBUnmountVol (paramBlock: ParmBlkPtr) : OSErr; 
paramBlock A pointer to a basic File Manager parameter block. 
Parameter block 

<- ioResul t OSErr The result code of the hmction, 

ioNamePtr StringPtr A pointer to a pathname. 

^ ioVRefNum Integer A volume reference number, a 



working directory reference number, 
or 0 for the default volume. 



DESCRIPTION 



The PBUnmountVol function unmounts the specified volume. All user files on the 
volume must be closed- Then, PBUnmountVol calls PBFlushVol to flush the volume 
and releases the memory used for the volume. 
The PBUnmountVol function always executes synchronously. 

WARNING 

Don't unmount the startup volume. Doing so will cause a 
system crash, a 

Note 

Unmounting a volume does not dose working directories; to release the 
memory allocated to a working directory, call PBCloseWD. ♦ 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBUrunountVol is _UnmountVol. 
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RESULT CODES 



PBEject 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad volume name 


f BsyErr 


-47 


One or more files are 


paramErr 


-50 


No default volume 


nsDrvErr 


-56 


No such drive 


extFSErr 


-58 


External file system 



I 



When your application is finished with a volume, you can use the PBEject function to 
place the volume offline and eject it. 

FUNCTION PBEject (paramBlock : ParniBlkPtr) : OSErr; 
paramBlock A pointer to a basic File Manager parameter block. 
Parameter block 

ProcPtr 



2! 



0) 

a> 



loCompletion 

<r- ioResult 
— > ioNamePtr 
-> ioVRefNum 



A pointer to a completion 
routine. 

OSErr The result code of the function. 

StringPtr A pointer to a pathname. 
Integer A volume specification. 



DESCRIPTION 



The PBEject function flushes the specified volume, places it offline, and then ejects 
the volume ' 



ASSEMBLY-LANGUAGE INFORMATION 

n^e trap macro for PEE j ec t is _E j ec t . You can invoke the _E j ect macro asynchro- 
nously; the first two parts of the call are executed synchronously, and the achial ejection 
IS executed asynchronously. ^ 



RESULT CODES 



noErr 

nsvErr 

ioErr 

bdNamErr 

paramErr 

nsDrvErr 

extFSErr 



0 No error 

-35 No such volume 

-36 I/O error 

-37 Bad volume name 

-50 No default volimie 

-56 No such drive 

-58 External file system 
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PBOffLine 



You can use the PBOffLine function to place a volume offline. Most applications don't 
need to do this. 

FUNCTION PBOffLine (paramBlock: ParmBlkPtr) : OSErr; 
paramBlock A pointer to a basic File Manager parameter block. 

A pointer to a completion routine. 
The result code of the function. 
A pointer to a pathname. 
A volume specification. 

DESCRIPnON 

The PBOf f Line function places the specified volume offline by calling PBFlushVol to 
flush the volume and releasing all the memory used for the volume except for the 
volume control block. 

The PBOffLine function always executes synchronously 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBOffLine is _0f f Line. 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad volume name 


paramErr 


-50 


No default volume 


nsDrvErr 


-56 


No such drive 


extFSErr 


-58 


External file system 



Updating Volumes ^ 

You can update a volvune by calling the PBFlushVol function. 



Parameter block 

ioCompletion ProcPtr 

<- ioResult OSErr 

-> ioNamePtr StringPtr 

-> ioVRefNum Integer 
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PBFlushVol 



You can use the PBFlushVol function to write the contents of the volume buffer and 
update information about the voliune. 

FUNCTION PBFlushVol (paramBlock: ParmBlkPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 

ioCompletion 
<r~ ioResult 
— > ioNamePtr 
— > ioVRefNum 



Proc Ft r A pointer to a completion routine. 

OSErr The result code of the function. 

Str ingPt r A pointer to a pathname. 

Integer A volume specification. 



DESCRIPTION 



On the volume specified by ioNamePtr or ioVRefNum, the PBFlushVol function 
writes descriptive information about the volume, the contents of the associated volume 
buffer, and all access path buffers for the volume (if they've changed since the last time 
PBFlushVol was called). 

Note 

The date and time of the last modification to the volume are set when 
the modification is made, not when the volume is flushed. ♦ 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBFlushVol is _FlushVol. 



RESULT CODES 



noErr 

nsvErr 

ioErr 

bdNamErr 

paramErr 

nsDrvErr 

extFSErr 



0 No error 

-35 No such volume 

-36 I/O error 

-37 Bad volume name 

-50 No default volume 

-56 No such drive 

-58 External file system 
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Obtaining Volume Information 

The File Manager provides several routines that allow you to obtain and modify 
information about a volume. For example, you can use the PBHGetVInf o function 
to determine the date and time that a volume was last modified. You can use the 
PBHGetVol Farms function to determine other features of the volume, such as 
whether it supports the PBHOpenDeny function. 



FBHGetVInfo - 

You can use the PBHGetVInf o function to get detailed information about a volume. 

FUNCTION PBHGetVInf o (paramBlock : HParmBlkPtr ; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<— 


ioResult 


OSErr 


The result code of the function. 




ioNamePtr 


StringPtr 


A pointer to the volume's name. 


<-> 


ioVRefNum 


Integer 


On input, a volume specification. 






On output, the volume reference 








number. 


-4 


ioVol Index 


Integer 


An index used for indexing through 




all mounted volumes. 


<- 


ioVCrDate 


Iiongint 


The date and time of initialization. 


<- 


ioVLsMod 


Longint 


The date and time of last 








modification. 


<~- 


ioVAtrb 


Integer 


The volume attributes. 


<r- 


ioVNmFls 


Integer 


The number of files in the root 








directory. 


ir- 


ioVBitMap 


Integer 


The first block of the volume bitmap. 


ir- 


ioVAllocPtr 


Integer 


The block at which the next new 








file starts. 


<r~ 


ioVNmAlBlks 


Integer 


The nimiber of allocation blocjcs. 




ioVAlBlkSiz / 


Longint 


The size of allocation blocks. 




ioVClpSiz 


Longint 


The default clump size. 


<- 


ioAlBlSt 


Integer 


The first block in the volvune 








block map. 




ioVNxtCNID 


Longint 


The next unused catalog node ID. 




ioVFrBlk 


Integer 


The number of unused 








allocation blocks. 




ioVSigWord 


Integer 


The volume signature. 


<- 


ioVDrvInfo 


Integer 


The drive number. 




ioVDRefNum 


Integer 


The driver reference number. 
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4- 


ioVFSID 


Integer 


ir- 


ioVBkUp 


Longint 


<r~ 


ioVSeqNum 


Integer 


ir- 


ioVWrCnt 


Longint 


<— 


ioVFilCnt 


Longint 


ir- 


ioVDirCnt 


Longint 


<— 


ioVFndrlnfo 


ARRAY ( 1 



-8] 



The file system handling 
this volume. 

The date and time of the last backup. 
Used internally. 
The volume write count 
The number of files on the volume. 
The number of directories on 
the volume. 
OF Longint 

Information used by the Finder. 



The PBHGetVInf o function returns information about the specified volume. If the value 
of iovol Index is positive, the File Manager attempts to use it to find the volume; for 
instance, if the value of ioVolIndex is 2, the FUe Manager attempts to access the second 
mounted volume in the VCB queue. If the value of ioVolIndex is negative, the File 
Manager uses ioNamePtr and ioVRef Num in the standard way to determine the 
volume. If the value of ioVolIndex is 0, the File Manager attempts to access the 
volume by using ioVRef Num only. The volume reference number is returned in 
ioVRef Num, and the volume name is returned in the buffer whose address you passed 
in ioNamePtr. You should pass a pointer to a Str31 value if you want that name 
returned. If you pass NIL in the ioNamePtr field, no volume name is returned. 

If you pass a working directory reference number in ioVRef Num (or if die default 
directory is a subdirectory), the number of files and directories in the specified directory 
(the directory's valence) is returned in ioVNmFls. 

You can read the ioVDrvInf o and ioVDRef Num fields to determine whether the 
specified volume is online, offline, or ejected. For online volumes, ioVDrvInf o contains 
the drive number of the drive containing the specified volume and hence is always 
greater than 0. If the value rehirned in ioVDrvInf o is 0, the volume is either offline or 
ejected. You can determine whether the volume is offline or ejected by inspecting the 
value of the ioVDRef Num field. For online volumes, ioVDRef Num contains a driver 
reference number; these numbers are always less than 0. If the volume is not online, the 
value of ioVDRef Num is either the negative of the drive ntimber (if the volume is offline) 
or the drive number itself (if the volimie is ejected). 

You can get information about aU the orUine volumes by making repeated calls to 
PBHGetVInf o, starting with the value of ioVolIndex set to 1 and incrementing tfiat 
value until PBHGetVInf o returns nsvErr. 



SPECIAL CONSIDERATIONS 

The values returned in the ioVNmAlBlks and ioVFrBlk fields are unsigned integers. 
You need to exercise special care when reading those values fi-om Pascal. See 
"Determining the Amount of Free Space on a Volume" on page 2-46 for one technique 
you can use to read those values. 



File Manager Reference 2-145 



TIVO-408595 



CHAPTER 2 



File Manager 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHGetVInf o is _HGetVolInf o. 



RESULT CODES 



noErr 

nsvErr 

paramErr 



0 No error 
-35 No such volume 
-50 No default volume 



PBSetVInfo 



You can use the PBSetVInfo function to change information about a volume. 

FUNCTION PBSetVInfo (paramBlock : HParmBlkPtr; async: Boolean): 

OSErr ; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<— 


ioResult 


OSErr 


The result code of the function. 


-> 


ioNamePtr 


String Ptr 


A pointer to the volume's name. 


-> 


ioVRefNum 


Integer 


A volume specification. 




ioVCrDate 


Longlht 


The date and time of initialization. 




ioVLsMod 


Longint 


The date and time of last 








modification. 


-> 


ioVAtrb 


Integer 


The volume attributes. 


— > 


ioVBkUp 


Longint 


The date and time of the last 








backup. 




ioVSeqNum 


Integer 


Used internally. 


-> 


ioVFndrlnf o 


ARRAY [1. .8] 


OF Longint 








Information used by the Finder. 



DESCRIPTION 

The PBSetVIn f o function lets you modify information about volumes. You can specify, 
in ioNamePt r, a pointer to a new name for the volume. Only bit 15 of ioVAt rb can be 
changed; setting it locks the volume. 

Note 

You cannot specify the volume by name; you must use either the 
volume reference number, the drive number, or a v/orking directory 
reference number. ♦ 
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ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBSetVInfo is_SetVolInf o. 

RESULT CODES 

noErr 0 No error 

nsvErr -35 No such volume 

paramErr -50 No default volume 

PBHGetVolParms 



You can use the PBHGetVolParms function to determine the characteristics of a volume. 

FUNCTION PBHGetVolParms (paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 




ioResult 


OSErr 


The result code of the function. 


-> 


ioNamePtr 


StringPtr 


A pointer to the volume's name. 




ioVRefNum 


Integer 


A volume specification. 




ioBuf fer 


Ptr 


A pointer to a GetVolParmsInfoBuf f er 
record. 




ioReqCount 


Longint 


The size of the buffer area. 


<— 


ioActCount 


Longint 


The size of the data actually returned. 



DESCRIPTION 

The PBHGetVolParms function returns information about the characteristics of a 
volume. You specify a volume (either by name or by volume reference number) and a 
buffer size, and PBHGetVolParms fills ixi the volume attributes buffer, as described in 
this section. 

You can use a name (pointed to by the ioNairiePtr field) or a volim\e specification 
(contained in the ioVRefNum field) to specify the volimie. A volume specification can be 
a volume reference number, drive number, or working directory reference number. If 
you use a volume specification to specify the volume, you should set the ioNamePtr 
field to. NIL. 

You must aUocate memory to hold the returned attributes and put a pointer to the buffer 
in the ioBuf f er field. Specify the size of the buffer in the ioReqCount field. The 
PBHGetVolParms function places the attributes information in the buffer pointed to by 
the ioBuf f er field and specifies the actual length of the data in the ioActCount field. 
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The PBHGetVolParms function returns the bulk of its volume description in the 
vMAt tr ib field of the attributes buffer. The vMAttr ib field contaii\s 32 bits of 
attribute information about the volume. Bits 0-3 and 21-24 are reserved; all volumes 
should return these bits clear. The bits currently used are defined by these constants: 



CONST 

bHasBlankAccessPrivi leges 



= 4 

bHasBTreeMgr = 5 
bHasFilelDs = 6 
bHasCatSearch - 7 
bHasUserGroupList 

= 8; 

bHasPersonalAccessPrivileges 



{volume supports inherited privileges} 
{reserved} 

{volume supports file ID functions} 
{volume supports PBCatSearch} 

{volume supports AFP privileges} 





9; 


{local file sharing is enabled} 


bHasFolderLock = 


10? 


{volume supports locking of folders} 


bHasShortName = 


11; 


{volume supports AFP short names} 


bHasDesktopMgr = 


12; 


{volume supports Desktop Manager} 


bHasMoveRename = 


13; 


{volume supports _MoveRename} 


bHasCopyFile 


14; 


{volume supports _CopyFile} 


bHasOpenDeny = 


15; 


{volume supports shared access modes} 


bHasExtFSVol 


16; 


{volume is external file system volume} 


bNoSysDir 


17; 


{volume has no system directory} 


bAccessCntl 


18. 


{volume supports AFP access control} 


bNoBootBlks 


19 


; {volume is not a startup volume} 


bWoDeskl terns 


20 


{do not place objects on the desktop} 


bNoSwitchTo 


25 


{do not switch launch to applications} 


bTrshOffLine = 


26 


{zoom volume when it is unmounted} 


bNoLclSync = 


27 


{don't let Finder change mod. date} 


bNoVNEdit 


28 


; {lock volume name} 


bNoMiniFndr 


29 


{reserved; always 1} 


bLocalWList 


30 


; {use shared volume handle for window } 






{ list} 


bLimitFCBs 


31; {limit file control blocks} 



These constants have the following meanings if set: 



Constant descriptions 

bHasBlankAccessPrivi leges 

This volume supports inherited access privileges for folders. 

Reserved for internal use. 

This volume supports the file ID fimctior\s, including the 
PBExchangeFiles function. 
This volume supports the PBCatSearch fvmction. 



bHasBTreeMgr 
bHasFilelDs 



bHasCatSearch 
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bHasUserGroupList 

This volume supports the Users and Groups file and thus the AFP 
privilege functions. 

bHasPersonalAccessPrivi leges 

This volume has local file sharing enabled. 

bHasFolderLock Folders on the volume can be locked, and so they carmot be deleted 
or renamed. 

bHasShortName This volume supports AFP short names. 

bHasDesktopMgr This volume supports all of the desktop functions (described - in 
the chapter "Desktop Manager" in Inside Macintosh: More 
Macintosh Toolbox). 

bHasMoveRename This volume supports the PBHMoveRename function. 
bHasCopyFi le This volume supports the PBHCopyFile function, which is used in 

copy and duplicate operations if both source and destination 

volumes have the same server address. 



bHasOpenDeny 

bHasExtFSVol 
bNoSysDir 

bAccessCntl 



bNoBootBlks 

bNoDeskI terns 
bNoSwitchTo 
bTrshOf fLine 

bNoLclSync 
bNpVNEdit 
bNoMiniFndr 
bLocalWList 

bLimitFCBs 



This volume supports the PBHOpenDeny and PBHOpenRFDeny 
functions. 

This volume is an external file system volume. 

This volume doesn't support a system directory. Do not switch 
launch to this volume. 

This volume supports AppleTalk AFP access-control interfaces. The 

PBHGetLoginInf o, PBHGetDirAccess, PBHSetDirAccess, 

PBHMapID, and PBHMapName functions are supported. Special 

folder icons are used. The Access Privileges menu command is 

enabled for disk and folder items. The ioFlAttrib field of 

PBGetCatInf o calls is assiuned to be valid. 

This volume is not a startup volume. The Startup menu item is 

disabled. Boot blocks are not copied during copy operations. 

Don't place objects in this volume on the Finder desktop. 

The Finder will not switch launch to any application on this volume. 

Any time this volume goes offline, it is zoomed to the Trash 
and unmounted. 

Don't let the Finder change the modification date. 
This volume's name carmot be edited. 
Reserved; alwiays set to 1. 

The Finder uses the returned shared volume handle for its local 
window list. 

The Finder limits the nimiber of file control blocks used during 
copying to 8 instead of 16. 



SPECIAL CONSIDERATIONS 

A volume's characteristics can change when the user enables and disables file sharing. 
You niight have to make repeated calls to PBHGetVolParms to ensure that you have the 
current status of a volume. 
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ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHGetVol Farms are 
Trap macro Selector 

_HFSDispatch $0030 



RESULT CODES 

noErr 0 No error 

nsvErr -35 Volume not found 

paramErr -50 Volume doesn't support the function 



Manipulating the Default Voliune 

The low-level functions PBGetVol, PBSetVol, PBHGetVol, and PBHSetVol allow you 
to manipulate the default volume and directory. 



PBGetVol 



You can use the PBGetVol function to determine the default volume and default 
directory. 

FUNCTION PBGetVol (paramBlock: ParmBlkPtr; async: Boolean): OSErr; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 

— > ioCompletion ProcPtr 

<r- ioResult OSErr 

<r~ ioNamePtr StringPtr 

i— ioVRefNum Integer 



A pointer to a completion routine. 
The result code of the function. 
A pointer to a pathname. 
A volume reference number 
or a working directory 
reference number. 



DESCRIPTION 

The PBGetVol function returns, in ioNaraePtr, a pointer to the name of the default 
volume (unless ioNamePtr is NIL) and, in ioVRefNum, its volume reference number. If 
a default directory was set with a previous call to PBSetVol, a pointer to its name is 
returned in ioNamePtr and its working directory reference number is returned in 
ioVRefNum. However, if, in a previous call to HSetVol (or PBHSetVol), a working 
directory reference number was passed in, PBGetVol returns a volume reference 
number in the ioVRefNum field. 
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ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBGetVol is „GetVol. 



RESULT CODES 



noErr 0 No error 

nsvErr -35 No default volume 



PBSetVol 



You can change the default volume and default directory using the PBSetVol function. 
FUNCTION PBSetVol (paramBlock: ParmBlkPtr; async: Boolean) : OSErr; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 

-> ioCompletion ProcPtr A pointer to a completion routine. 

^ ioResult OSErr The result code of the function. 

ioNamePtr StringPtr A pointer to a pathname. 

ioVRef Num Integer A volume reference number or a 

working directory reference number. 



DESCRIPTION 

If you pass a volume reference number in ioVRef Num, the PBSetVol function makes 
the specified volume the default volume and the root directory of that volume the 
default directory. If you pass a working directory reference number, PBSetVol makes 
the specified directory the default directory, and the volume contairung that directory 
the default volume. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBSetVol is _Se tVol. 



RESULT CODES 



noErr 
nsvErr 
bdNamErr 
paramErr 



0 No error 

-35 No such volimie 

-37 Bad volume name 

-50 No default volume 
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PBHGetVol 



You can use the PBHGetVol function to determine the default volume and default 
directory. 

FUNCTION PBHGeCVol (paramBlock: WDPBPtr; async: Boolean): OSErr; 

paramBlock A pointer to a working directory parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 



(FALSE) execution. 



Parameter block 



-> 


ioCompletion 


ProcPtr 


<- 


ioResult 


OSErr 


<- 


ioNamePtr 


StringPtr 


<r- 


ioVRefNum 


Integer 


<r- 


ioWDProcID 


Longint 




ioWDVRefNum 


Integer 




ioWDDirlD 


Longint 



A pointer to a completion routine. 

The result code of the function. 

A pointer to a pathnanae. 

A volume reference number or a working 

directory reference number. 

The working directory user identifier. 

The volume reference number of the 

default volume. 

The directory ID of the default directory. 



DESCRimON 

The PBHGetVol function returns the default volume and directory last set by a call 
to either PBSetVol or PBHSetVol. The reference number of the default volume is 
returned in ioVRefNum, The PBHGetVol function returns a pointer to the volume s 
name in the ioNamePtr field. You should pass a pointer to a St r 3 1 value if you 
want that name returned. If you pass NIL in the ioNamePtr field, no volume name 
is returned. 

A WARNiNG 

On exit, the ioVRefNum field contains a working directory reference 
number (instead of the volume reference number) if, in the last call to 
PBSetVol or PBHSetVol, a working directory reference number was 
passed in this field, a 

The volume reference number of the volume on which the default directory exists 
is returned in ioWDVRe f Num. Hie directory ID of the default directory is returned 
in ioWDDiria 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHGetVol is _HGetVol. 



RESULT CODES 

noErr 0 No error 

ns vEr r -35 No default volume 
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PBHSetVol 



The PBHSetVol function sets both the default volume and the default directory. 
FUNCTION PBHSetVol (paramBlock : WDPBPtr; async : Boolean): OSErr; 

paramBlock A pointer to a working directory parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



A pointer to a completion routine. 
The result code of the function. 
A pointer to a pathname. 
A volume reference number or a 
working directory reference number. 
The directory ID. 

DESCRIPTION 

The PBHSetVol function sets the default volume and directory to the volume and 
directory specified by the ioNamePtr, ioVRefNum, and ioWDDirlD fields. 

The PBHSetVol function sets the default volume to the volume specified by the 
ioVRef Num field, which can contain either a volume reference number or a working 
directory reference number. If the ioNamePtr field specifies a full pathname, however, 
the default volume is set to the volume whose name is contained in that pathname. (A 
full pathname overrides the ioVRef Num field.) 

The PBHSetVol function also sets the default directory If the ioVRefNum field contains 
a volume reference number, then the default directory is set to the directory on that 
volume having the partial pathname specified by ioNamePtr in the directory specified 
by ioWDDirlD. If the value of ioNamePtr is NIL, the default directory is simply the 
directory whose directory ID is contained in ioWDDirlD. 

If the ioVRefNum field contains a working directory reference number, then ioWDDirlD 
is ignored and the default directory is set to the directory on that volume having the 
partial pathname specified by ioNamePtr in the directory specified by the working 
directory reference number. If the value of ioMamePtr is NIL, the default directory is 
sirhply the directory specified in i oVRe f Num. 

A WARNING 

Use of the PBHSetVol function is discouraged if your application may 
execute in system software versions prior to version 7.0. Because the 
specified directory might not itself be a working directory, PBHSetVol 
records the default volume and directory separately, using the volume 
reference number of the volume and the actual directory ID of the 
specified directory. Subsequerit calls to GetVol (or PBGetVol) return 
only the volume reference number, which will cause that volume's root 
directory (rather than the default directory, as expected) to be accessed. A 
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Note 

Both the default volume and the default directory are used in calls made 
with no volume name, a volume reference number of 0, and a directory 
IDofO. ♦ 



ASSEMBLY LANGUAGE INFORMATION 

The trap macro for PBSGetVol is _HSetVol. 



RESULT CODES 



noErr 

nsvErr 

bdNamErr 

fnfErr 

paramErr 

afpAccessDenied 



0 No error 

-35 No such volume 

-37 Bad volume name 

-43 Directory not found 

-50 No default volume 

-5000 User does not have access to the directory 



File System Specification Routines 

The FUe Manager provides a set of file and directory manipulation routines that accept 
file system specification records as parameters. Depending on the requirements of your 
application and on the envkonment in which it is running, you may be able to 
accomplish all your file and directory operations by using these routines. 
Before calling any of these routines, however, you should call the Ges tal t function to 
ensure that they are available in the operating environment. If these routines are not 
available, you can caU the corresponding HFS routines. See '^High-Level HFS Routines" 
on page 2-169 for details. 



Opening Files ^ 

There are two FSSpec functions that allow you to open files, FSpOpenDF and 
FSpOpenRF. You can use them to open a file's data fork and resource fork, respectively 



FSpOpenDF - 

You can use the FSpOpenDF fimction to open a file's data fork. 

FUNCTION FSpOpenDF (spec: FSSpec; permission: SignedByte; 

VAR refNum: Integer ): "OSErr ; 

An FSSpec record specifying the file whose data fork is to be opened. 
A constant indicating the desired file access permissions. 
A reference number of an access path to the file's data fork. 
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DESCRIPTION 



The FSpOpenDF function opens the data fork of the file specified by the spec parameter 
and returns a file reference number in the ref Nujn parameter. You can pass that reference 
number as a parameter to any of the low- or high-level file access routines. 

The permission parameter specifies the kind of access permission mode you want. 
In most cases, you can simply set the permission parameter to f sCurPerm. Some 
applications request f sRdWrPerm, to ensure that they can both read from and write 
to a file. For more information about permissions, see "FUe Manipulation" on page 2-7. 
In shared environments, permission requests are translated into the deny mode 
permissions defined by AppleShare. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpOpenDF are 
Trap macro Selector 

_HighLevelHFSDispatch $0002 



RESULT CODES 



noErr 0 

nsvErr -35 

ioErr -36 

bdNamErr -37 

tmfoErr -42 

fnfErr -43 

opWrErr -49 

permErr -54 

dirNFErr -120 
a f pAcces sDeni ed -5000 



No error 

No such volume 

I/O error 

Bad fUename 

Too many files open 

File not found 

File already open for writing 
Attempt to open locked fQe for writing 
Directory not found or incomplete pathname 
User does not have the correct access to the file 



FSpOpenRF 



You can use the FSpOpenRF function to open a file's resource fork. 

FUNCTION FSpOpenRF (spec: FSSpisc; permission: SignedByte; 

VAR refNum: Integer) : OSErr; 

spec An FSSpec record specifying the file whose resource fork is to be opened. 

permission A cor\stant indicating the desired file access permissions. 

r e f Num A reference number of an access path to the file's resource fork. 



DESCRIPTION 



The FSpOpenRF IFunction creates an access path to the resource fork of a file and returns, 
in the refNum parameter, an access path reference number to that fork. You can pass that 
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reference number as a parameter to any of the low- or high-level file access routines. 
; The permi s s i on parameter should contain a constant indicating the desired file 

access permissions. 

SPECIAL CONSIDERATIONS 

Generally, your application should use Resource Manager routines rather than File 
Manager routines to access a file's resource fork. The FSpOpenRF hinction does not read 
the resource map into memory and is generally useful only for applications (such as 
utilities that copy files) that need block-level access to a resource fork. In particular, you 
shotdd not use the resource fork of a file to hold nonresource data. Many parts of the 
system software assume that a resource fork always contains resoturce data. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpOpenRF are 
Trap macro Selector 

_HighLevelHFSDispatch $0003 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


tmfoErr 


-42 


Too many files open 


fnfErr 


-43 


FUe not found 


opWrErr 


-49 


File already open for writing 


permErr 


-54 


Attempt to open locked file for writing 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 



Creating and Deleting Files and Directories 

You can create files and directories by calling FSpCreate and FSpDirCreate, 
respectively. You can delete files and directories by calling the FSpDelete function. 

FSpCreate 



You can use the FSpCreate function to create a new file. 

FUNCTION FSpCreate (spec: FSSpec; creator: OSType; 

fileType: OSType; scriptTag: Script Code) : 
OSErr; 

spec An FSSpec record specif)ring the file to be created. 
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The creator of the new file. 
The file type of the new file. 

The code of the script system in which the filename is to be displayed. If 
you have established the name and location of the new file using either the 
StandardPutFile or CustomPutFile procedure, specify the script 
code returned in the reply record. (See the chapter "Standard File Package" 
in this book for a description of StandardPutFile and 
CustomPutFile.) Otherwise, specify the system script by setting the 
scriptTag parameter to the value smSystemScript. 

DESCRIPTION 

The FSpCreate function creates a new file (both forks) with the specified type, creator, 
and script code. The new file is imlocked and empty. The date and time of creation and 
last modification are set to the current date and time. 

See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentiab for 
information on file types and creators. 

Files created using FSpCreate are not automatically opened. If you want to write data to 
the new fUe, you must first open the file using a file access routine (such as FSpOpenDF). 

Note 

The resource fork of the new file exists but is empty. You'll need to 
call one of the Resource Manager procedures CreateResFile, 
HCreateResFile, or FSpCreateResFile to create a resource map in 
the file before you can open it (by calling one of the Resource Manager 
functions OpenResFile, HOpenResFile, or FSpOpenResFile). ♦ 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpCreate are 
Trap macro Selector 

_HighLevelHFSDispatch $0004 

RESULT CODES 



noErr 


0 


No error 


dirFulErr 


-33 


File directory fuU 


dskFulErr 


-34 


Disk is full 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


-43 


Directory not found or incomplete pathname 


wPrErr 


-44 


Hardware volvune lock 


vLckdErr 


-46 


Software volume lock 


dupFNErr 


-48 


EKiplicate filename and version 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access 


af pOb j ectTypeErr 


-5025 


A directory exists with that name 
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FSpDirCreate 



You can use the FSpDirCreate function to create a new directory. 

FUNCTION FSpDirCreate (spec: FSSpec; scriptTag: Script Code ; 

VAR createdDirlD: Longint) : OSErr; 

spec An FSSpec record specifying the directory to be created. 

scriptTag The code of the script system in which the directory name is to be 

displayed. If you have established the name and location of the new 
directory using eidier the StandardPutFile or CustomPutFile 
procedure^ specify the script code returned in the reply record. (See the 
chapter "Standard File Package" in this book for a description of 
StandardPutFile and CustomPutFile.) Otherwise, specify the 
system script by setting the scriptTag parameter to the value 
smSystemScript. 

createdDirlD 

The directory ID of the directory that was created. 



DESCRIFHON 



The FSpDirCreate function creates a new directory and returns the directory ID of the 
new directory in the createdDirlD parameter. Then FSpDirCreate sets the date and 
time of creation and last modification to the current date and time. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpDirCreate are 
Trap macro Selector 

_HighLevelHFSDispatch $0005 



RESULT CODES 



noErr Q error 

dirFulErr -33 File directory full 

dskFulErr -34 Disk is hill 

nsvErr ~~3S No such volume 

ioErr -36 I/O error 

bdNamErr -37 Bad filename 

f n f Er r -43 Directory not f oimd or incomplete pathname 

wPrErr -44 Hardware volume lock 

vLckdErr -45 Software volume lock 

dupFNErr -48 DupUcate filename and version 

di rNFEr r _120 Directory not foimd or incomplete pathname 

wrgVoliypErr -123 Not an HFS volume 

afpAccessDenied -5000 User does not have the correct access ^ 
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FSpDelete 



You can use the FSpDelete function to delete files and directories. 

FUNCTION FSpDelete (spec: FSSpec) : OSErr; 

spec An FSSpec record specifying the fUe or directory to delete. 



DESCRIPTION 



The FSpDelete function removes a fUe or directory. If the specified target is a file, both 
forks of the file are deleted. The file ID reference, if any, is removed. 
A file must be closed before you can delete it. Similarly, a directory must be empty 
before you can delete it. If you attempt to delete an open file or a nonempty directory, 
FSpDelete returns the result code f BsyErr. FSpDelete also rehims the result 
code f BsyErr if the directory has an open working directory associated with it. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpDelete are 
Trap macro Selector 

_HighLevelHFSDispatch $0006 



RESULT CODES 



noErr 


0 


nsvErr 


-35 


ioErr 


-36 


bdNamErr 


-37 


fnfErr 


-43 


wPrErr 


-44 


fLckdErr 


-45 


vLckdErr 


-46 


fBsyErr 


-47 


dirNFErr 


-120 


a f pAc c es sDeni ed 


-5000 



No error 
No such volume 
I/O error 
Bad filename 
File not found 
Hardware volume lock 
File is locked 
Software volume lock 

File busy, directory not empty, or working directory 
control block operi 

Directory not found or incomplete pathname 
User does not have the correct access 



Accessing Information About Files and Directories 



You can use several File Manager routines that accept FSSpec records if you want to 
obtain and set information about files and directories and to manipulate file locking. 
These routines don't require the file to be open. 
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FSpGetFInfo 

You can use the FSpGetFInfo function to obtain the Finder information about a file or 
directory. 

FUNCTION FSpGetFInfo (spec: FSSpec; VAR fndrlnfo: FInfo) : OSErr; 

spec An FSSpec record specifying the file or directory whose Finder 

information is desired. 

fndrlnfo Ir\formation used by the Finder. 

DESCRIFnON 

The FSpGetFInfo function returns the Finder information from the volume catalog 
entry for the specified file or directory. The FSpGetFInfo function provides only the 
original Finder information— the FInfo or Dinf o records, not FXInf o or DXInf o. (See 
the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for a 
discussion of Finder information,) 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpGetFInfo are 
Trap macro Selector 

_HighLevelHFSDispatch $0007 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


-43 


File not found 


paramErr 


-50 


No default volume 


dirNFErr 


-120 


Directory not fotmd or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access 


af pOb j ectTypeErr 


-5025 


Directory not fotmd or incomplete pathname 



FSpSetFInfo 

You can use the FSpSetFInfo function to set the Finder information about a fQe 
or directory. 

FUNCTION FSpSetFInfo (spec: FSSpec; fndrlnfo: FInfo): OSErr; 

spec An FSSpec record specifying the file or directory whose Finder 

information will be set. 

fndrlnfo Information to be used by the Finder. 
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DESCRIPTION 



The FSpSetFinf o function changes the Finder information in the volume catalog entry 
for the specified file or directory. FSpSetFinf o allows you to set only the original 
Fmder information— the FInf o or DInf o records, not FXinf o or DXInf o. (See the 
chapter 'Tinder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for a 
discussion of Finder information.) 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpSetFinf o are 
Trap macro Selector 

_HighLevelHFSDispatch $0008 



RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


-43 


File not found 


wPrErr 


^4 


Hardware volume lock 


fLckdErr 


-45 


File is locked 


vLckdErr 


-46 


Software volume lock 


dirNFErr 
afpAccessDenied 


-120 
-5000 


Directory not fotmd or incomplete pathnj 
User does not have the correct access 


a f pOb j ec tTypeErr 


-5025 


Object was a directory 



FSpSetFLock 

You can use the FSpSetFLock function to lock a file. 
FUNCTION FSpSetFLock (spec: FSSpec) : OSErr; 
spec An FSSpec record specifying the file to lock. 

DESCRIPTION 

The FSpSetFLock function locks a file. After you lock a file, aU new access paths to that 
file are read-only This function has no effect on existing access paths. 

If the PBHGetVolParms function indicates that the volume supports folder locking (that 
is, the bHasFolderLock bit of the vMAttrib field is set), you can use FSpSetFLock to 
lock a directory. 
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ASSEMBLY-LANGUAGE INFORMATION 

; The trap macro and routine selector for FSpSetFLock are 

Trap macro Selector 

-HighLevelHFSDispatch $0009 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


fnfErr 


^3 


File not found 


wPrErr 


-44 


Hardware volume lock 


vLckdErr 


-46 


Software volume lock 


dirNFErr 


-120 


EHrectory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 


afpObjectTypeErr 


-5025 


Folder locking not supported by volume 



FSpRstFLock 



You can use the FSpRstFLock function to unlock a file. 
FUNCTION FSpRstFLock (spec: FSSpec) : OSErr; 
spec An FSSpec record specifying the file to unlock. 

DESCRimON 

The FSpRstFLock function ur\locks a file. 

If the PBHGet Vol Farms function indicates that the volume supports folder locking (that 
is, the bHasFolderLock bit of the vMAttrib field is set), you can use FSpRstFLock to 
unlock a directory. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpRstFLock are 
Trap macro Selector 

_HighLevelHFSDispatch $O0OA 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


fnfErr 


-43 


File not foimd 


wPrErr 


-44: 


Hardware voliune lock 


vLckdErr 


-46 


Software volume lock 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 


af pOb j ectTypeEr r 


-5025 


Folder locking not supported by volume 
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You can use the FSpRename function to rename a file or directory. 

FUNCTION FSpRename (spec: FSSpec; newName: Str255) : OSErr; 

spec An FSSpec record specifying the file or directory to rename. 

newName The new name of the file or directory. 

DESCRIPTION 

The FSpRename function changes the name of a file or directory. If a file ID reference for 
the specified file exists, it remains with the renamed file. 

SPECIAL CONSIDERATIONS 

If you want to change the name of a new copy of an existing file, you should use the 
FSpExchangeFiles function instead. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpRename are 
Trap macro Selector 

__HighLevelHFSDispatch $000B 

RESULT CODES 



noErr 


0 


No error 


dirFulErr 


-33 


File directory full 


dskFulErr 


-34 


Volume is full 


nsvErr 


-35 


No such volume 


ioErr 


-36 


1/ O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


-43 


File not found 


wPrErr 


-44 


Hardware volume lock 


f LckdErr 


-45 


File is locked 


vLckdErr 


-46 


Software volume lock 


dupFNErr 


^8 


Duplicate filename and version 


paramErr 


-50 


No default volume 


f sRnErr 


-59 


Problem during rename 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 



Moving Files or Directories 

The FSpCatMove functiori allows you to move files and directories v^thin a volume. If 
the FSSpec routines are not available, you can call the high-level HFS routine CatMove 
or the low-level HFS routine PBCatMove. 
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FSpCatMove 



You can use the FSpCatMove function to move a file or directory from one location to 
another on the same volume. 

FUNCTION FSpCatMove (source: FSSpec; dest: FSSpec) : OSErr; 



The FSpCatMove function moves the file or directory specified by the source 
parameter into the directory specified by the dest parameter. The directory ID specified 
in the parlD field of the dest parameter is the directory ID of the parent of the 
directory into which you want to move the source file or directory. The name field of the 
dest parameter specifies the name of the directory into which you want to move the 
source file or directory. 

Note 

If you don't already know the parent directory ID of the destination 
directory it might be easier to use the PBCatMove function, which 
allows you to specify only the directory ID of the destination directory. ♦ 

The FSpCatMove function is strictly a file catalog operation; it does not actually change 
the location of the file or directory on the disk. You carmot use FSpCatMove to move 
a file or directory to another volimie (that is, the vRef Num field in both FSSpec 
parameters must be the same). Also, you cannot use FSpCatMove to rename files or 
directories; to rename a file or directory use FSpRename. 



dest 



source 



An FSSpec record specifying the name and location of the file or 
directory to be moved. 

An FSSpec record specifying the name and location of the directory into 
which the source file or directory is to be moved. 



DESCRIPTION 



ASSEMBLY-LANGUAGE INFORMATION 



The trap macro and routine selector for FSpCatMove are 
Trap macro Selector 

_HighLevelHFSDispatch $000C 
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RESULT CODES 



noErr g 

nsvErr _35 

ioErr .35 

bdNamErr -37 

fnfErr .43 

wPrErr -44 

fLckdErr ^5 

vLckdErr -45 

dupFNErr -43 

parainErr _50 

badMovErr -122 

wrgVolTypErr -123 
afpAccessDenied -5000 



No error 

No such volume 

I/O error 

Bad fileriame or attempt to move into a file 

File not found 

Hardware volume lock 

Target directory is locked 

Software volume lock 

Duplicate filename and version 

No defavilt volxmie 

Attempt to move into offspring 

Not an HFS volume 

User does not have the correct access to the file 



Exchanging the Data in Two F iles 

The FSpExchangeFiles function allows you to exchange the data in two files. 



FSpExchangeFiles 



You can use the FSpExchangeFiles function to exchange the data stored in two files 
on the same volume. 

FUNCTION FSpExchangeFiles (source: FSSpec; dest: FSSpec) : OSErr; 



source 



The source file. The contents of this file and its file information are placed 
in the file specified by the dest parameter. 

des t The destination file. The contents of tiiis file and its file information are 

placed in the file specified by the source parameter. 



DESCRIPTION 



The FSpExchangeFiles function swaps the data in two files by changing the 
information in the volume's catalog and, if the files are open, in the file control 
blocks. You should use FSpExchangeFiles when updating an existing file, so 
that the file ID remains vafid in case the file is being tracked through its file ID. 
The FSpExchangeFiles fimction changes the fields in the catalog entries that 
record the location of the data and the modification dates. It swaps both the data 
forks and the resource forks. 

The FSpExchangeFiles fimction works on both open and closed files. If either file is 
open, FSpExchangeFiles updates any file control blocks associated with the file. 
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- Exchanging the contents of two files requires essentially the same access permissions as 

; opening both files for writing. 

The files whose data is to be exchanged must both reside on the same volume. If they do 
not, FSpExchangeFiles returns the result code dif f VolErr. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for FSpExchangeFiles are 
Trap macro Selector 

_HighLevelHFSDispatch $000F 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


Volume not found 


ioErr 


-36 


I/O error 


fnfErr 


-43 


File not found 


f LckdErr 


^5 


File is locked 


vLckdErr 


-46 


Volume is locked or read-only 


paramErr 


-50 


Function not supported by volume 


volOf f linErr 


-53 


Volume is offline 


wr gVo iTypEr r 


-123 


Not an HFS volvune 


diffVolErr 


-1303 


Files on different volumes 


afpAccessDenied 


-5000 


User does not have the correct access 


af pOb j ectTypeErr 


-5025 


Object is a directory, not a file 


af pSameOb j ectErr 


-5038 


Sotirce and destination files are the same 



Creating File System Specifications 

You can use either the FSMakeFSSpec function or the PBMakeFSSpec function to 
create FSSpec records. You should always use FSMakeFSSpec or PBMakeFSSpec 
to create an FSSpec record rather than allocating space and filling out the fields of the 
record yourself. 



FSMakeFSSpec 



You can use the FSMakeFSSpec function to initialize an FSSpec record to particular 
values for a file or directory. 

FUNCTION FSMakeFSSpec (vRefNum: Integer; dirlD: Longint; 

fileName: Str255; VAR spec: FSSpec) : 
OSErr; 
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vRefNum 



dirlD 



f ileName 



spec 



A volume specification. This parameter can contain a volume reference 
number, a working directory reference number, a drive number, or 0 
(to specify the default volume). 

A directory specification. This parameter usually specifies the parent 
directory ID of the target object. If the directory is suffidentiy specified 
by either the vRef Nam or f ileName parameter, dirlD can be set to 0. 
If you explicitly specify dirlD (that is, if it has any value other than 0), 
and if vRef Num specifies a working directory reference number, dirlD 
overrides the directory ID included in vRef Nuitu If the f ileName 
parameter contains an empty string, FSMakeFSSpec creates an 
FSSpec record for a directory specified by either the dirlD or 
vRef Num parameter. 

A full or partial pathname. If f ileName specifies a full pathname, 
FSMakeFSSpec ignores both the vRef Num and dirlD parameters. A 
partial pathname might identify only the final target, or it might include 
one or more parent directory names. If f ileName specifies a partial 
pathname, then vRef Num, dirlD, or both must be vaHd. 

A file system specification to be filled in by FSMakeFSSpec. 



DESCRIPTION 



The FSMakeFSSpec function fills in [he fields of the spec parameter using the 
information contained in the other three parameters. CaU FSMakeFSSpec whenever you 
want to create an FSSpec record. 

You can pass the input to FSMakeFSSpec in any of the ways described in "HFS 
Specifications" on page 2-28. See Table 2-10 on page 2-35 for information about the way 
FSMakeFSSpec interprets its input. 

If the specified volume is mounted and the specified parent directory exists, but the 
target file or directory doesn't exist in that location, FSMakeFSSpec fills in the record 
and then rehims f nf Err instead of noErr. The record is valid, but it describes a target 
that doesn't exist. You can use the record for other operations, such as creating a file with 
the FSpCreate function. 

In addition to the result codes that follow, FSMakeFSSpec can return a number of other 
File Manager error codes. If your application receives any result code other than noErr 
or f nf Err, aU fields of the resulting FSSpec record are set to 0. 



ASSEMBLY LANGUAGE INFORMATION 

The trap macro and routine selector for FSMakeFSSpec are 
Trap macro Selector 

_H i ghLevel HFSD i spa t ch $0001 
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RESULT CODES 



noErr 

nsvErr 

fnfErr 



0 No error 
-35 Volume doesn't exist 

-43 File or diirectory does not exist (FSSpec is stiU vabd) 



PBMakeFSSpec 



You can use the low-level PBMakeFSSpec function to create an FSSpec record for a file 
or directory. 

FUNCTION PBMakeFSSpec (paramBlock: HPannBlkPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 



(FALSE) execution. 



Parameter block 

ioCompletion 
<- ioResult 
-> ioNamePtr 
-> ioVRefNum 

ioMisc 

ioDirlD 



ProcPtr 

OSErr 

StringPtr 

Integer 

Longlnt 

Longint 



A pointer to a completion routine. 

The result code of the function. 

A pointer to a file or directory name. 

A volume specification. 

A pointer to an FSSpec record. 

A parent directory ID. 



DBSCRimON . 

Given a complete specification for a file or directory, the PBMakeFSSpec function hlls m 
an FSSpec record that identifies the file or directory. (See Table 2-10 on page 2-35 for a 
detailed description of valid file specifications.) 

If the specified volume is mounted and the specified parent directory exists, but the 
target file or directory doesn't exist in that location, PBMakeFSSpec fills m the record 
and returns fnfErr instead of noEr r. The record is valid, but it describes a target that 
doesn't exist You can use the record for another operation, such as creatmg a file. 
In addition to the result codes that follow, PBMakeFSSpec can rehim a number of 
different File Manager error codes. When PBMakeFSSpec returns any result other 
than noErr or fnfErr, all fields of the resulting FSSpec record are set to 0. 



ASSEMBLY-IANGUAGE INFORMATION 

The trap macro and routine selector for PBMakeFSSpec are 
Trap macro Selector 

_HFSbispatch $001B 
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RESULT CODES 

noErr 0 No error 

nsvErr -35 Volvime doesn't exist 

f nf Err -43 File or directory does not exist (FSSpec is still valid) 



High-Level HFS Routines 

The File Manager provides, a set of high-level file and directory manipulation routines 
that are available in all operating environments. You may need to use these routines if 
the FSSpec routines are not available. You do not need to call the Gestal t function to 
determine if these routines are available. 

Each of the high-level HFS routines allows you to specify a file or directory by providing 
three parameters: a volume specification, a directory specification, and a filename. See 
"HFS Spedficatipns" on page 2-28 for a complete description of the many ways in which 
you can set these parameters to pick out a file or directory. 



Opening Files 

You can use the functions HOpenDF, HOpenRF, and HOpen to open files. 



HOpenDF 



You can use the HOpenDF function to open the data fork of a file. 

FUNCTION HOpenDF (vRefNum: Integer; dirlD: Longint; 

fileName: Str2 55; permission: SignedByte; 
VAR refNum: Integer) : OSErr; 

vRef Niun A volume reference number, a working directory reference number, or 0 
for the default volume. 

dirlD A directory ID. 

f i 1 eName The name of the file. 

permission The access mode under which to open the file, 

re f Num The file reference number of the opened file. 



DESCRIPTION 

The HOpenDF function creates an access path to the data fork of a file and returns, in 
the refNum parameter, an access path reference number to that fork. You can pass that 
reference number as a parameter to any of the high-level file access routines. 
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RESULT CODES 



noErr 


0 


nsvErr 


-35 


ioErr 


-36 


bdNamErr 


-37 


tmfoErr 


-42 


fnfErr 


-43 


opWrErr 


-49 


permErr 


-54 


dirNFErr 


-120 


a f pAcces sDeni ed 


-5000 



No error 

No such volume 

I/O error 

Bad filei\aine 

Too many files oper\ 

File r\ot foui\d 

File already oper\ for writing 
Attempt to open locked file for writing 
Directory not foimd or incomplete pathname 
User does not have the correct access to the file 



HOpenRF „ 

You can xase the HOpenRF function to open the resource fork of file. 

FUNCTION HOpenRF {vRefNum: Integer; dirlD: Longint; 

fileName: Str255; permission: SignedByte; 
VAR refNum: Integer): OSErr; 

vRef Num A volvime reference number, a working directory reference number, or 0 

for the default volume. 
dirlD A directory ID. 

f i 1 eName The name of the file. 

permission The access mode imder which to open the file, 
re f Num The file reference number of the opened file. 



DESCRIPTION 

The HOpenRF function creates an access path to the resource fork of a file. A file 
reference nvunber for that file is returned in the refNum parameter. 



SPECUL CONSIDERATIONS 

Generally, your application should use Resoturce Manager routines rather than File 
Manager routines to access a file's resoiurce fork. The HOpenRF function does not read 
the resource map into memory and is generally useful orUy for applicatior\s (such as 
utilities that copy files) that need block-level access to a resource fork. In particular, you 
should not use the resoturce fork of a file to hold noru^source data. Many parts of the 
system software asstune that a resource fork always contains resource data. 
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RESULT CODES 



noErr 


0 


nsvErr 


-35 


ioErr 


-36 


bdNamErr 


-37 


tmf oErr 


-42 


fnfErr 




opWrErr 




permErr 


-54 


dirNFErr 


-120 


afpAccessDenied 


-5000 



No error 

No such volume 

I/O error 

Bad filename 

Too many files open 

File not found 

File already open for writing 
Attempt to open locked file for writing 
Directory not found or incomplete pathname 
User does not have the correct access to the file 



HOpen 



You can use the HOpen function to open the data fork of a file. Because HOpen also opens 
devices, it's safer to use the HOpenDF function instead. 

FUNCTION HOpen (vRefNtim: Integer; dirlD: Longlnt; 

fileName: Str255; permission: SignedByte; 
VAR refNum: Integer) : OSErr; 

vRe f Num A volume reference number, a working directory reference number, or 0 
for the default voliune. 

dirlD A directory ID. 

f i 1 eName The name of the file. 

permission The access mode under which to open the file, 

r e f Num The file reference number of the opened file. 



DESCRIPTION 



The HOpen funcHon creates an access path to the data fork of the specified file. A file 
reference number for that file is returned in the refNum parameter. 

WARNING 

If you use HOpen to try to open a file whose name begins with a period, 
you might mistakenly open a driver instead; subsequent attempts to 
write data might corrupt data on the target device. To avoid these 
problems, you should always use HOpenDF instead of HOpen. A 



File Manager Reference 



2-171 



TIVd-408621 



CHAPTER 2 



Re Manager 

RESULt CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


tmf oErr 


-42 


Too many files open 


fnfErr 


-43 


File not found 


opWrErr 


-A9 


File already open for writing 


permErr 


-54 


Attempt to open locked file for writing 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 



Creating and Deleting Files and Directories 

You can create a file by calling the HCreate function and a directory by calling the 
DirCreate function. To delete either a file or a directory, call HDelete. 



HCreate 



You can use the HCreate function to create a new file. 

FUNCTION HCreate (vRefNum: Integer; dirlD: Longint; 

fileName: Str255; creator: OSType; 
fileType: OSType) > OSErr; 



vRe f Nuxn A volume reference number, a working directory reference number, or 0 
for the default volume. 

dirlD A directory ID. 

f i 1 eName The name of the new file. 

c rea tor The creator of the new file. 

f i 1 eType The file type of the new file. 



DESCRlFnON 

The HCreate function creates a new file (both forks) with ti\e specified name, creator, 
and file type. For information on a file's creator and type, see the chapter "Finder 
Interface" in Inside Macintosh: Macintosh Toolbox Essentials. 

The new file is unlocked and empty. The date and time of its creation and last 
modification are set to the current date and time. 

Files created using HCreate are not automatically opened. If you want to write data to 
the new file, you must first open the file using a file access routine. 
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Note 



The resource fork of the new file exists but is empty. You'll need to 
call one of the Resource Manager procedures CreateResFile, 
HCreateResFile, or FSpCreateResFile to create a resource map in 
the file before you can open it (by calling one of the Resoiirce Manager 
functions OpenResFile, HOpenResFile, or FSpOpenResFile). ♦ 

You should not allow users to give files names that begin with a period (.). This ensures 
that files can be successfully opened by applications calling HOpen instead of HOpenDF. 



RESULT CODES 



noErr 


0 


No error 


dirFulErr 


-33 


File directory full 


dskFulErr 


-34 


Disk is full 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


-43 


Directory not foimd or incomplete pathname 


wPrErr 


-44 


Hardware volume lock 


vLckdErr 


-46 


Software volume lock 


dupFNErr 


-48 


Duplicate filename and version 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access' 


af pOb j ectTypeErr 


-5025 


A directory exists with that name 



DirCreate 



You can use the DirCreate function to create a new directory. 

FUNCTION DirCreate (vRefNum: Integer; parentDirlD: Longint; 

direct cry Name: Str255; 
VAR createdDirlD: Longint) : OSErr; 



vRefNum 



parentDirlD 



A volume reference number, a working directory reference number, 
or 0 for the default volume. 



The directory ID of the parent directory; if it's 0, the new directory 
is placed in the root directory of the specified volume. 

directoryName The name of the new directory. 

createdDirlD The directory ID of the created directory. 



DESCRIFnON 



The DirCreate function creates a new directory and returns the directory ID of the new 
directory in the createdDirlD parameter. The date and time of its creation and last 
modification are set to the current date and time. 
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Note 

A directory ID, imlike a volume reference number or a working 
directory reference number, is a Longint value. ♦ 



RESULT CODES 



noErr 

dirFulErr 

dskFulErr 

nsvErr 

ioErr 

bdNaitiErr 

fnfErr 

wPrErr 

vLckdErr 

dupFNErr 

dirNFErr 

wrgVolTypErr 

afpAccessDenied 



0 No error 

-33 File directory full 

-34 Disk is full 

-35 No such volume 

-36 I/O error 

-37 Bad filename 

-43 Directory not fovmd or incomplete pathname 

-44 Hardware volume lock 

-46 Software volume lock 

^8 Duplicate filename and version 

-120 Directory not found or incomplete pathname 

-123 Not an HFS voliune 
-5000 User does not have the correct access 



HDelete 

You can use the HDelete function to delete a file or directory. 

FUNCTION HDelete (vRefNum: Integer; dirlD: Longint; 

fileName: Str255) : OSErr; 

A volume specification (a volume reference number, a working directory 
reference number, or 0 for the default volume). 
The directory ID of the parent of the file or directory to delete. 
The name of the file or directory to delete. 



vRefNum 

dirlD 
fileName 



DESCRIPTION 

The HDelete hmction removes a file or directory. If the specified target is a file, both 
forks of the file are deleted. In addition, if a fOe ID reference for the specified file exists, 
that reference is removed. 

A file must be closed before you can delete it. Similarly, you cannot delete a directory 
imless if s empty. If you attempt to delete an open file or a nonempty directory, HDelete 
returns the result code f BsyErr. HDelete also returns the result code f BsyErr if the 
directory has an open working directory associated with it. 
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RESULT CODES 



noErr 0 

nsvErr -35 

ioErr -36 

bdNamErr -37 

fnfErr -43 

wPrErr -44 

fLckdErr -45 

vLckdErr -46 

fBsyErr -47 

dirNFErr -120 
afpAccessDenied -5000 



No error 
No such voliune 
I/O error 
Bad filename 
File not found 
Hardware volume lock 
File is locked 
Software voltime lock 

File busy, directory not empty, or working directory 
control block open 

Directory not fotmd or incomplete pathname 
User does not have the correct access 



Accessing Inf ormatiori About Files ai\d Directories 

The File Manager provides a number of high-level HFS routines that allow you to obtain 
and set information about files and directories and to manipulate file locking. All of the 
routines described in this section operate on both forks of a file and don't require the file 
to be open. 



HGetFInfo 



You can use the HGetFInfo function to obtain the Finder information for a file. 

FUNCTION HGetFInfo (vRefNum: Integer; dirlD: Longlnt; 

fileName: Str255; VAR fndrlnfo: FInfo) : 
OSErr; 

vRef Num A voltane reference number, a working directory reference number, or 
0 for the default voliune. 

dirlD A directory ID. 

f i 1 eName The name of the file. 

f ndr In f o Information used by the Finder. 



DESCRIPTION 

The HGetFInfo function returns the Hnder information stored in the volvune's catalog 
for a file. The HGetFInfo function returns only the original Finder information— -the 
FInfo record, not FXInf o. (See the chapter "Finder Interface" in Inside Macintosh: 
Macintosh Toolbox Essentials for a discussion of Finder information.) 
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RESUltCODES 



noErr 


0 


nsvErr 


-35 


ioErr 


-36 


bdNamErr 


-37 


fnfErr 


-43 


paramErr 


-50 


dirNFErr 


-120 


afpAccessDenied 


-5000 


a f pOb j ec t TypeEr r 


-5025 



No error 

No such volume 

I/O error 

Bad filename 

File not found 

No default volume 

Directory not found or incomplete pathname 
User does not have the correct access 
Directory not found or incomplete pathname 



HSetFInfo 



You can use the HSetFInfo function to set the Finder information for a file, 

FUNCTION HSetFInfo (vRefNum: Integer; dirlD: Longint; 

fileName: Str255; fndrlnfo: FInfo) : OSErr; 

vRe f Num A volume reference number, a working directory reference number, or 0 
for the default volume. 

dirlD A directory ID. 

f i 1 eName The name of the file. 

fndrlnfo Information used by the Finder. 



DESCRimON 



The HSetFInfo function changes the Finder information stored in the volume's catalog 
for a file. HSetFInfo changes only the original Finder information — the FInfo record, 
not FXInf o, (See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox 
Essentials for a discussion of Finder information.) 



RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


^3 


File not fovmd 


wPrErr 


-44: 


Hardware volume lock 


fLckdErr 


-45 


FUe is locked 


vLckdErr 


-46 


Software volume lock 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access 


af pOb j ectTypeErr 


-5025 


Object was a directory 
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HSetFLock 



You can use the HSetFLock function to lock a file. 

FUNCTION HSetFLock (vRefNum: Integer; dirlD: Longint; 

fileName: Str255) : OSErr; 

vRef Num A volume reference number, a working directory reference number, or 0 
for the default volume. 

dirlD A directory ID. 

f i 1 eName The name of the file. 

DESCRimON 

The HSetFLock function locks a file. After you lock a file, all new access paths to that 
file are read-only. This function has no effect on existing access paths. 

If the PBHGetVolParms function indicates that the volume supports folder locking (that 
is, the bHasFolderLock bit of the vMAt trib field is set), you can use HSetFLock to 
lock a directory. 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


fnfErr 


-43 


File not found 


wPrErr 


-44 


Hardware volume lock 


vLckdErr 


-46 


Software voltune lock 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 


afpObjectTypeErr 


-5025 


Folder locking not supported by volume 



HRstFLock 



You can use the HRstFLock function to unlock a file. 

FUNCTION HRstFLock (vRefNum: Integer; dirlD: Longint; 

fileName: Str255) : OSErr; 

vRef Num A volume reference number, a working directory reference number, or 0 
for the default volume. 

dirlD A directory ID. 

f i 1 eName The name of the file. 
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DESCRIPTION 

* The HRstFLock function unlocks a file. 

If the PBHGe t Vo 1 Farms function indicates that the volume supports folder locking (that 
is, the bHasFolderLock bit of the vMAt tr ib field is set), you can use HRstFLock to 
unlock a directory. 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


fnfErr 


^3 


File not found 


wPrErr 


-AA 


Hardware volume lock 


vLckdErr 


-46 


Software volume lock 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 


af pObj ectTypeErr 


-5025 


Folder locking not supported by volume 



HRename 



You can use the HRename function to rename a file, directory, or volume. 

FUNCTION HRename (vRefNum: Integer; dirlD: Longint; 

oldName: Str255; newName: Str255) : OSErr; 

vRe f Num A volume reference number, a working directory reference number, or 0 
for the default volume. 

dirlD A directory ID. 

oldName An existing filename, directory name, or volume name. 
newName The new filename, directory name, or volume name. 

DESCRIPTION 

The HRename function changes the name of a file, directory, or volume. Given the name 
of a file or directory in oldName, HRename changes it to the name in newName, Given a 
volume name or a volume reference number, it changes the name of the volume to the 
name in newName. Access paths currently in use aren't affected. 

SPECIAL CONSIDERATIONS 

You cannot use HRename to change the directory in which a file resides. If you're 
renaming a volume, make sure that both names end with a colon. 

Note 

If a file ID reference exists for a file you are renaming, the file ID remains 
vdth the renamed file. ♦ 
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RESULT CODES 



noErr 


0 


No error 


dirFulErr 


-33 


File directory full 


dskFulErr 


-34 


Volume is full 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


-43 


File not foimd 


wPrErr 


-44 


Hardware volimie lock 


fLckdErr 


-45 


File is locked 


vLckdErr 


-46 


Software volume lock 


dupFNErr 


-48 


Ehiplicate fUename 


paramErr 


-50 


No default volume 


f sRnErr 


-59 


Problem during rename 


dirNFErr 


-120 


EMrectory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 



Moving FUes or Directories 



The high-level HFS function CatMove allows you to move files and directories within 
a volume. 



CatMove 



You can use the CatMove function to move files or directories from one directory to 
another on the same volume. 



FUNCTION CatMove (vRefNum: Integer; dirlD: Longint; 

oldName: Str2 55; newDirlD: Longint; 
newName: Str255) : OSErr; 



vRefNum 

dirlD 

oldName 

newDirlD 

newName 



A volume reference number, a working directory reference number, or 0 
for the default volvune. 

A directory ID. 

An existing filename or directory name. 

If newName is empty, the directory ID of the target directory; otherwise, 
the parent directory ID of the target directory. 

The name of the directory to which the file or directory is to be moved. 



DESCRIPTION 



The CatMove fimction moves a file or directory from one directory to another within a 
volume. CatMove is strictly a file catalog operation; it does not actually change the 
location of the file or directory on the disk. 
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The newName parameter specifies the name of the directory to which the file or directory 
is to be moved. If a valid directory name is provided for newMame, the destination 
directory's parent directory is specified in newDirlD. However, you can specify an 
empty name for newName, in which case newDirlD should be set to the directory ID of 
the destination directory. 

Note 

It is usually simplest to specify the destination directory by passing its 

directory ID in the newDir ID parameter and by setting newName to an 

empty name. To specify an empty name, set newName to ' : ' . ♦ 

The CatMove hmction cannot move a file or directory to another volume (that is, the 

vRe f Num parameter is used in specifying both the source and the destination). Also, you 

cannot use it to rename files or directories; to rename a file or directory, use HRename. 



RESULT CODES 



noErr 


0 


nsvErr 


-35 


ioErr 


-36 


bdNamErr 


-37 


fnfErr 


-43 


wPrErr 


-44: 


fLckdErr 


-45 


vLckdErr 


-46 


dupFNErr 


-48 


paramErr 


-50 


badMovErr 


-122 


wrgVolTypErr 


-123 


afpAccessDenied 


-5000 



No error 

No such volume 

I/O error 

Bad filename or attempt to move into a file 

File not found 

Hardware volume lock 

Target directory is locked 

Software volume lock 

Duplicate filename and version 

No default volume 

Attempt to move into offspring 

Not an HPS volume 

User does not have the correct access to the file 



Maintaini ng Working Directories 

The File Manager provides several fiinctions that allow you to manipulate working 
directories. Working directories are used intemaUy by the FUe Manager; in general, 
your application should not create or directly access working directories- For more 
information about working directories, see "Working Directory Reference Numbers/' 
beginning on page 2-26. 



OpenWD 

You can use the OpenWD function to create a working directory. 

FUNCTION OpenWD (vRefNura: Integer; dirlD: Longint ; 

procID: Longint; VAR wdRefNum: Integer): OSErr; 
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DESCRimON 



vRe f Num A volume reference number, a working directory reference nimiber, or 0 
for the default volume. 

dirlD Adirectory ID. 

prociD A v^orking directory user identifier. You should use your application's 
signature as the user identifier. 

wdRef Num On exit, the working directory reference number. 



The OpenWD function creates a working directory that corresponds to the specified 
directory. It returns in wdRef Num a working directory reference number that can be used 
in subsequent File Manager calls. 

If a working directory having the specified user identifier already exists for the specified 
directory, no new working directory is opened; instead, the existing working directory 
reference number is returned in wdRef Num. If the specified directory already has a 
working directory with a different user identifier, a new working directory reference 
number is returned. 

If the directory specified by the dirlD parameter is the volume's root directory, no 
working directory is created; instead, the volume reference number is returned in the 
wdRef Num parameter. 



RESULT CODES 



noErr 0 

nsvErr -35 

fnfErr -43 

tmwdoErr -121 

afpAccessDenied -5000 



No error 

No such volume 

No such directory 

Too many working directories open 

User does not have the correct access to the file 



CloseWD 

You can use the C los eWD function to dose a working directory. 
FUNCTION CloseWD (wdRefNum: Integer) : OSErr; 
wdRe f Num A working directory reference niunber. 

DESCRIPTION 

The CloseWD function releases the specified working directory. 
Note 

If you specify a voltune reference nimnber in the wdRef Num parameter, 
CloseWD does nothing. ♦ 
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RESULT GODES 



noErr 

nsvErr 

rfNumErr 



0 No error 
-35 No such volume 

-51 Bad working directory reference number 



GelWDInfo 



You can use the GetWDInf o function to get information about a working directory. 

FUNCTION GetWDInf o (wdRefNum: Integer; VAR vRefNum: Integer ; 

VAR dirlD: LongInt; VAR procID: LongInt) : 
OSErr; 

wdRe f Nim A working directory reference number. 

vRef Num If nonzero on input, a volume reference number or drive number. On 

output, the volume reference number of the working directory. 
dirlD On output, the directory ID of the specified working directory. 

procID The working directory user identifier 



DESCRIPTION 

The GetWDInf o hmction returns information about the specified working directory. 
You can use GetWDInf o to convert a working directory reference number to its 
corresponding volume reference number and directory ID. 



RESULT CODES 

noErr 0 No error 

nsvErr -35 No such volume 

r f NumEr r -51 Bad working directory reference number 



Low-Level H FS Routines 

The File Manager provides a set of low-level file and directory manipulation routines 
that are available in all operating environments. You do not need to call the Gestalt 
function to determine if these routines are available. 

These routines exchange parameters with your application through a parameter block. 
When you call a low-level routine, you pass the address of the appropriate parameter 
block to the routine. 

Some low-level HFS routines can run either asynchronously or synchronously Each of 
these routines comes in three versions: one version requires the a sync parameter, and 
two have the suffix Async or Sync added to their names. For more information about 
the differences between the three versions, see "Low-Level File Access Routines" on 
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page 2-120. Only the first version of these routines is documented in this section. See 
''Summary of the File Manager/' beginning on page 2-240, for a listing that includes all 
three versions. 

Assembly-Language Note 

See the assembly-language note on page 2-120 for details on calling 
these routines from assembly language. ♦ 

Operdng Files 

You can use the functions PBHOpenDF, PBHOpenRF, and PBHOpen to open files. 



PBHOpenPF ' 

You can use the PBHOpenDF fvinction to open the data fork of a file. 

FUNCTION PBHOpenDF (paramBlock : HParmBlkPtr; async: 

OSErr; 

paramBlock A pointer to a basic HFS parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 






-> 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<— 


ioResult 


OSErr 


The residt code of the function. 




ioNamePtr 


StringPtr 


A pointer to a pathname. 




ioVRefNum 


Integer 


A voltmie specification. 




ioRefWum 


Integer 


A file reference nimtiber. 




ioPerrassn 


SignedByte 


The read /write permission. 




ioDirlD 


Longint 


A parent directory ID. 



fa 



Boolean) : 



DESCRIPTION 

The PBHOpenDF function creates an access path to the data fork of a file and returns a 
file reference number in the ioRef Nvun field. PBHOpenDF is exactiy like the PBHOpen 
function except that PBHOpenDF allows you to open a file whose name begins with 
a period (.). 

You can open a path for writing even if it accesses a file on a locked volume, and no error 
is returned imtil a PBWrite, PBSetEOF, or PBAllocate call is made. 

If you attempt to open a locked file for writing, PBHOpenDF returns the result code 
permErr. If you request exclusive read/write permission but another access path 
is already open, PBHOpenDF returr\s the reference number of the existing access path 
in ioRefNum and opWrErr as its function result. You should not use this reference 
number imless your application originally opened the file. 
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ASSEMBLY-LANGUAGE INFORMATION 



The trap macro and routine selector for PBHOpenDF are 
Trap macro Selector 

„HFSDispatch $001 A 



RESULT CODES 



noErr 



nsvErr 
ioErr 



bdNaiuErr 

tmf oErr 

fnfErr 

opWrErr 

permErr 

dirNFErr 



afpAccessDenied 



0 

-35 
-36 
-37 
-42 
-43 
-49 
-54 
-120 
-5000 



No error 

No such volume 

I/O error 

Bad filename 

Too many files open 

File not found 

File already open for writing 
Attempt to open locked file for writing 
Directory not fotmd or incomplete pathname 
User does not have the correct access to the file 



PBHOpenRF 



You can use the PBHOpenRF function to open the resource fork of file. 

FUNCTION PBHOpenRF (paramBlock : HParmBlkPtr ; async : Boolean): 

OSErr ; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 



— > 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 




ioResult 


OSErr 


The result code of the function. 




ioNamePtr 


StringPtr 


A pointer to a pathname. 


— > 


ioVRefNum 


Integer 


A volume specification. 




ioRefNum 


Integer 


A file reference number. 


— > 


ioPermssn 


SignedByte 


The read /write permission. 


-> 


ioDirlD 


Longint 


A directory ID. 



DESCRIPTION 

The PBHOpenRF function creates an access path to the resource fork of a file and returns 
a file reference number in the ioRefNum field. 
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SPECIAL CONSIDERATIONS 

Generally your application should use Resource Manager routines rather than File 
Manager routines to access a file's resource fork. The PBHOpenRF function does not read 
the resource map into memory and is generally useful only for applications (such as 
utilities that copy files) that need block-level access to a resource fork. In particular, you 
should not use the resource fork of a file to hold nonresource data. Many parts of the 
system software assume that a resource fork always contains resource data. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHOpenRF is _HOpenRF. 



RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


tmf oErr 


-42 


Too many files open 


fnf Err 


-43 


File not found 


opWrErr 


-49 


File already open for writing 


permErr 


-54 


Attempt to open locked file for writing 


dirNFErr 


-120 


Directory not found or iiicomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 



PEHOpen 

You can use the PBHOpen function to open the data fork of a file. Because PBHOpen will 
also open devices, it's safer to use the PBHOpenDF function instead. 

FUNCTION PBHOpen (paramBlock : HParmBlkPtr ; async: Boolean): OSErr; 
paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 



-> 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


f- 


ioResult 


OSErr 


The result code of the function. 




ioNamePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volvune specification. 




ioRefNum 


Integer 


A file reference number. 


-> 


ioPennssn 


SignedByte 


The read / write permission. 


-> 


ioDirlD 


Longint 


A directory ID. 
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; The PBHOpen function creates an access path to the data fork of the specified file and 
returns a file reference number in the ioRef Num field. 

You can open a path for writing even if it accesses a file on a locked volume, and no error 
is returned until a PBWrite, PBSetEOF, or PBAllocate call is made. 

If you attempt to open a locked file for writing, PBHOpen returns the result code 
permErr. If you request exclusive read /write permission but another access path is 
already open, PBHOpen returns the reference number of the existing access path in 
ioRef Num and opWrErr as its function result. You should not use this reference number 
ui^ess your application originally opened the file. 

▲ WARMING 

If you use PBHOpen to try to open a file whose name begins with a 
period, you might mistakenly open a driver iristead; subsequent 
attempts to write data might corrupt data on the target device. To 
avoid these problems, you should always use PBHOpenDF ii\stead 
of PBHOpen. A 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHOpen is „HOpen. 



No error 
No such volume 
1/ O error 
Bad filename 
Too many files open 
File not found 

File already open for writing 
Attempt to open locked file for writing 
Directory not found or incomplete pathname 
User does not have the correct access to the file 

Creating and Deleting Files and Directories 

You can create a file by calling the PBHCr ea t e function and a directory by calling the 
PBDirCreate function. To delete either a file or a directory use PBHDelete. 



PBHCreate 



You can use the PBHCreate function to create a new file. 

FUNCTION PBHCreate (paramBlock : HParmBlkPtr; async: Boolean): 

OSErr; 
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RESULT CODES 



noErr 


0 


nsvErr 


-35 


ioErr 


-36 


bdNamErr 


-37 


tmf oErr 


-42 


fnfErr 


-43 


opWrErr 


-49 


permErr 


-54 


dirNFErr 


-120 


afpAccessDenied 


-5000 
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par amBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

A pointer to a completion routine. 
The result code of the function. 
A pointer to a pathname. 
A volume specification. 
A directory ID. 



Parameter block 



-> 


ioCompletion 


ProcPtr 


<— 


ioResult 


OSErr 


— > 


ioNamePtr 


StringPtr 


-> 


ioVRefNum 


Integer 


-> 


ioDirlD 


Long In t 



DESCRIPTION 

The PBHCreate function creates a new file (both forks); the new file is unlocked and 
empty. The date and time of its creation and last modification are set to the current date 
and time. If the file created isn't temporary (that is, if it wQl exist after the user quits the 
application), the application should call PBHSetFInf o (after PBHCreate) to fill in the 
information needed by the Finder. 

Files created using PBHCreate are not automaticaUy opened. If you want to write 
data to the new file, you must first open the file using a file access routine (such 
as PBHOpenDF). 

Note 

The resource fork of the new file exists but is empty. You'll need to 
call one of the Resource Manager procedures CreateResFile, 
HCreateResFile, or FSpCreateResFile to create a resource map in 
the file before you can open it (by calling one of the Resource Manager 
functions OpenResFile, HOpenResFile, or FSpOpenResFile). ♦ 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHCreate is _HCreate. 



RESULT CODES 



noErr 0 

dirFulErr -33 

dskFulErr -34 

nsvErr -35 

ioErr -36 

bdNamErr -37 

fnfErr -43 

wPrErr -44 

vLckdErr -46 

dupFNErr ^8 

dirNFErr -120 
afpAccessDenied -5000 
afpObjectTypeErr -5025 



No error 

File directory fiill 
Disk is full 
No such volume 
I/O error 
Bad filename 

EHrectory not foiind or incomplete pathname 

Hardware volume lock 

Software volume lock 

Duplicate filename and version 

Directory not found or incomplete pathname 

User does not have the correct access 

A directory exists with that name 
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PBDitCreate 

You can use the PBDirCreate function to create a new directory. 

FUNCTION PBDirCreate {paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 



— > 


ioCompletion 


ProcPtr 


A pointer to a completion routine: 


<— 


ioResult 


OSErr 


The result code of the function. 


<-> 


ioNamePtr 


StringPtr 


A pointer to a pathname. 




ioVRefNum 


Integer 


A volume specification. 


<-> 


ioDirlD 


Longint 


A directory ID. 



DESCRimON 

The PBDirCreate function is identical to PBHCreate except that it creates a new 
directory instead of a file. You can specify the parent of the directory to be created in 
ioDirlD; if it's 0, the new directory is placed in the root directory of the specified 
volume. The directory ID of the new directory is returned in ioDir ID. The date and 
time of its creation and last modification are set to the current date and time. 

Note 

A directory ID, unHke a volume reference number or a working 
directory reference number, is a Longint value. ♦ 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBDirCreate are 
Trap macro Selector 

_HFSDi spa t ch $0006 

RESULT CODES 



noErr 


0 


No error 


dirFulErr 


-33 


File directory full 


dskFulErr 


-34 


Disk is full 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


^3 


Directory not found or incomplete pathname 


wPrErr 


-44 


Hardware volume lock 


vLckdErr 


-46 


Software volume lock 


dupFNErr 


-48 


Duplicate filename and version 


dirNFErr 


-120 


Directory not found or incomplete pathname 


wrgVolTypErr 


-123 


Not an HFS volume 


afpAccessDenied 


-5000 


User does not have the correct access 
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PBHDelete 



You can use the PBHDelete function to delete a file or directory. 

FUNCTION PBHDelete {paramBlock: HParmBlkPtr ; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(false) execution. 

Parameter block 



-> 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


ir- 


ioResult 


OSErr 


The result code of the function. 


-> 


ioNamePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volume specification. 




ioDirlD 


Longint 


A directory ID. 



DESCRIFTION 

The PBHDelete function removes a file or directory. If the specified target is a file, both 
forks of the file are deleted. In addition, if a file ID reference for the specified file exists, 
that file ID reference is also removed. 

A file must be closed before you can delete it. Similarly, you carmot delete a directory 
unless it's empty. If you attempt to delete an open file or a nonempty directory, 
PBHDelete returns the result code f BsyErr. PBHDelete also returns f BsyErr if you 
attempt to delete a directory that has an open working directory associated with it. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHDelete is _HDelete. 



RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


^3 


File not found 


wPrErr 


-44 


Hardware volume lock 


fLckdErr 


-45 


File is locked 


vLckdErr 


-46 


Software volume lock 


fBsyErr 


-47 


File busy, directory not empty, or working directory 
control block open 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access 
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Accessing Information About Files and Directories 

The File Manager provides a number of low-level HFS routines that allov^ you to obtain 
and set information about files and directories and to manipulate file locking. All of the 
routines described in this section operate on both forks of a file and don't require the file 
to be open. 



PBGetCatlnfo 



You can use the PBGetCatlnfo function to get information about the files and 
directories in a file catalog. 

FUNCTION PBGetCatlnfo (paramBlock: CInfoPBPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to a catalog information parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block for files 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 




ioRjesult 


OSErr 


The result code of the function. 


<-> 


ioNamePtir 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volume specification. 


<— 


ioFRefNum 


Integer 


A file reference number. 


-> 


ioFDirlndex 


Integer 


An index. 




ioFlAttrib 


SignedByte 


The file attributes. 




ioFlFndrInf o 


FInfo 


Information used by the Finden 




ioDirlD 


LongInt 


On input, a directory ID. On output, a 
file ID. 




ioFlStBlk 


Integer 


The first allocation block of the 
data fork. 




ioFlLgLen 


LongInt 


The logical end-of-file of the data fork. 


<r- 


ioFlPyLen 


LongInt 


The physical end-of-file of the 
data fork. 


<- 


ioFlRStBlk 


Integer 


The first allocation block of the 
resource fork. 


<r~ 


ioFlRLgLen 


LongInt 


The logical end-of-file of the 
resoitrce fork. 


<r~ 


ioFlRPyLen 


LongInt 


The physical end-of-file of the 
resource fork. 


<- 


ioFlCrDat 


LongInt 


The date and time of creation. 


<- 


ioFlMdDat 


LongInt 


The date and time of the last 
modification. 


<- 


ioFlBkDat 


LongInt 


The date and time of the last backup. 




ioFlXFndrlnfo 


FXInfo 


Additional information used by 
the Finder. 




ioFlParlD 


LongInt 


The directory ID of the parent directory. 


<- 


ioFlClpSiz 


LongInt 


The file's clump size. 
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Parameter block for directories 

ioCompletion ProcPtr 

<r- ioResult OSErr 

^ ioNamePtr StringPtr 

ioVRefNum Integer 

-> ioFDirlndex Integer 

^ ioFlAttrib SignedByte 

<r- ioACUser SignedByte 

<r- ioDrUsrWds DInfo 

<r^ ioDrDirlD Longint 

<- ioDrNmFls Integer 

<r- ioDrCrDat Longint 

<- ioDrMdDat Longint 

<r- ioDrBkDat Longint 

<r- ioDrFndrlnfo DXInfo 



ioDrParlD 



Longint 



A pointer to a completion routine. 
The result code of the hmction. 
A pointer to a pathname. 
A volume specification. 
An index. 

The directory attributes. 
The directory access rights. 
Information used by the Finder. 
The directory ID. 

The nimiber of files in the directory. 
The date and time of creation. 
The date and time of the last 
modification. 

The date and time of the last backup. 
Additional information used by 
the Finder. 

The directory ID of the parent directory. 



I 



3 
01 
(Q 
0) 



DESCRIPTION 

The PBGetCatInf o function returns information about a file or directory depending on 
the values you specify in the ioFDirlndex, ioNamePtr, ioVRefNum, and ioDirlD or 
ioDrDir ID fields. If you need to determine whether the information returned is for a 
file or a directory you can test bit 4 of the ioFlAt trib field; if that bit is set, the 
information returned describes a directory 

The PBGetCatInf o function selects a file or directory according to these rules: 

■ If the value of ioFDirlndex is positive, PBGetCatInf o returns information about 
the file or directory whose directory index is ioFDirlndex in the directory specified 
by ioVRefNum (this will be the root directory if a volume reference number is 
provided). 

■ If the value of ioFDirlndex is 0, PBGetCatInf o rehims information about the file 
or directory specified by ioNamePtr in the directory specified by ioVRefNum (again, 
this will be the root directory if a volume reference number is provided). 

■ If the value of ioFDirlndex is negative, PBGetCatInf o ignores ioNamePtr and 
returns information about the directory specified by ioDrDirlD. 

With files, PBGetCatInf o is similar to PBHGetFInf o but rehims some additional 
information. If the file is open, the reference number of the first access path found is 
returned in ioFRef Num, and the name of the file is returned in ioNamePtr (unless 
ioNamePtr is NIL). The file's attributes are rehimed in the ioFlAttrib field. See 
the description of tiie fields of the CInf oPBRec data type (beginning on page 2-100) 
for the meaning of the bits in this field. 

Note 

V\?hen you get information about a file, the ioDirlD field contains the 
file ID on exit from PBGetCatInf o. You might need to save the value of 
ioDir ID before calling PBGetCatInf o if you make subsequent calls 
with the same parameter block. ♦ 
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With directories, PBGetCatInf o returns information such as the directory attnbutes 
and for server volumes, the directory access privileges of the user. The directory 
attributes are encoded by bits in the ioFlAttr ib field and have these meanmgs: 

Bit Meaning 

0 Set if the directory is locked 

1 Reserved 

2 Set if the directory is withiri a shared area of the directory hierarchy 

3 Set if the directory is a share point that is mounted by some user 

4 Set if the item is a directory 

5 Set if the directory is a share point 
^7 Reserved 

Note 

These bits in the ioFlAttr ib field for directories are read-only. 
You cannot alter directory attributes by setting these bits usmg 
PBSetCatInf o. Instead, you can call PBHSetFLock and 
PBHRstFLock to lock and unlock a directory, and PBShare 
and PBUnshare to enable and disable file sharing on local 
directories. ♦ 

The PBGetCatInf o hinction returns the directory access rights in the ioACUser 
field only for shared volumes. As a result, you should set this field to 0 before 
calling PBGetCatInf o. 

You can also use PBGetCat Info to determine whether a file has a file ID reference. 
The value of the file ID is returned in the ioDirlD field. Because that parameter could 
also represent a directory ID, call PBResolveFilelDRef to see if the value is a real 
file ID If you want to determine whether a file ID reference exists for a file and create 
one if it doesn't, use PBCreateFilelDRef , which will either create a file ID or 
return f idExists. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBGetCatInf o are 
Trap macro Selector 

_HFSDispatch $0009 



RESULT CODES 



noErr 

nsvErr 

ioErr 

bdNamErr 

fnfErr 

paramErr 

dirNFErr 

a f pAccessDeni ed 

af pOb j ec tTypeErr 



0 No error 

-35 No such volume 

-36 I/O error 

-37 Bad filename 

-43 File not found 

-50 No default volume 

-120 Directory not foimd or incomplete pathname 

-5000 User does not have the correct access 

-5025 Directory not found or incomplete pathname 



2-192 



File Manager Reference 



TIVO-408642 



CHAPTER 2 

File Manager 
PBSetCatlnfo 



You can use the PBSetCatlnfo function to modify information about fUes and 
directories. 

FUNCTION PBSetCatlnfo (paramBlock: CInfoPBPtr; async: Boolean): 

OSErr ; 

paramBlock A pointer to a catalog information parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block for files 





ioCompletion 


ProcPtr 


ir- 


ioResult 


OSErr 


-> 


ioNamePtr 


StringPtr 


-> 


ioVRefNum 


Integer 




ioFlFndrInf o 


FInfo 


-> 


ioDirlD 


Longint 




ioFlCrDat 


Longint 




ioFlMdDat 


Longint 


-> 


ioFlBkDat 


Longint 




ioFlXFndrlnfo 


FXInfo 


Parameter block for directories 


-> 


ioCompletion 


ProcPtr 


<- 


ioResult 


OSErr 


— > 


ioNamePtr 


StringPt] 


— > 


ioVRefNum 


Integer 


— > 


ioDrUsrWds 


DInfo 


_> 


ioDrDirlD 


Longint 


_> 


ioDrCrDat 


Longint 




ioDrMdDat 


Longint 


— > 


loDrBkDat 


Longint 


— > 


ioDrFndrlnfo 


DXInfo 



A pointer to a completion routine. 
The result code of the function. 
A pointer to a pathname. 
A volume specification, 
hiformation used by the Finder. 
The directory ID. 
The date and time of creation. 
The date and time of the last 
modification. 

The date and time of the last backup. 
Additional ir\formation used by 
the Finder. 



A pointer to a completion routine. 
The result code of the function. 
A pointer to a pathname. 
A volume specification. 
Liformation used by the Finder. 
The directory ID. 
The date and time of creation. 
The date and time of the last 
modification. 

The date and time of the last backup. 
Additional information used by 
the Finder. 



DESCRIPTION 

The PBSetCatlnfo hmction sets information about a file or directory. When used to set 
information about a file, it works much as PBHSetFinf o does, but lets you set some 
additional information. 
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assembIy-ianguage information 

The trap macro and routine selector for PBSetCatInf o are 
Trap macro Selector 

_HFSDispatch $OO0A 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


-43 


File not found 


fLckdErr 


-45 


File is locked 


vLckdErr 


-AG 


Volume is locked or read-orUy 


paramErr 


-50 


No default volume 


dirNFErr 


-120 


Directory not foimd or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access 



PBHGetFInfo 



You can use the PBHGetFInfo function to obtain information about a file. 

FUNCTION PBHGetFInfo {paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 




ioResult 


OSErr 


The result code of the function. 


<-> 


ioNamePtr 


StringPtr 


A pointer to a pathname. 




ioVRefNum 


Integer 


A volume specification. 




ioFRefNum 


Integer 


A file reference number. 




ioFDirlndex 


Integer 


An index. 




ioFlAttrib 


SignedByte 


The file attributes. 


ir- 


ioFlFndrlnfo 


FInfo 


Information used by the Finder. 


^ 


ioDirlD 


Long In t 


On input, a directory ID; on output, a file ID. 




ioFlStaik 


Integer 


The first allocation block of the data fork. 


<r- 


ioFlLgLen 


Longint 


The logical end-of-file of the data fork. 


<r~ 


ioFlPyLen 


Longint 


The physical end-of-file of the data fork. 


<r- 


ioFlRStBlk 


Integer 


The first allocation block of the resource fork. 


<r- 


ioFlRLgLen 


Longint 


The logical end-of-file of the resource fork. 


<r- 


ioFlRPyLen 


Longint 


The physical end-of-file of the resource fork. 


<r- 


ioFlCrDat 


Longint 


The date and time of creation. 


<r- 


ioFlMdDat 


Longint 


The date and time of last modification. 
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DESCRIPTION 

If the value of ioFDirlndex is positive, the PBHGetFInf o function returns 
information about the file whose directory index is ioFDirlridex on the volume 
specified by ioVRef Num in the directory specified by ioDirlD. You should call 
PBHGetFInf o just before PBHSetFInf o, so that the current information is present 
in the parameter block. 

Note 

If a working directory reference number is specified in ioVRef Num, the 
File Manager returns information about the file whose directory index is 
ioFDirlndex in the specified directory. ♦ 

If the value of ioFDirlndex is negative or 0, the PBHGetFInf o function returns 
information about the file having the name pointed to by ioNamePtr on the volume 
specified by ioVRef Num. If the file is open, the reference nimiber of the first access path 
foimd is returned in ioFRef Num, and the name of the file is returned in ioNamePtr 
(unless ioNamePtr is NIL). 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHGetFInf o is _HGetFileInf o. 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


bdNamErr 


-37 


Bad filename 


fnfErr 


-43 


File not f otmd 


paramErr 


-50 


No default volume 


dirNFErr 


-120 


Directory not fovmd or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access 


afpObjectTypeErr 


-5025 


Directory not found or incomplete pathname 



PBHSetFInfo 



You can use the PBHSetFInfo hmction to set ii\formation for a file. 

FUNCTION PBHSetFInfo (paramBlock; HParmBlkPtr ; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronoxis 

(FALSE) execution. 
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Parameter block 

_> ioCompletion 
<— ioResult 
ioNamePtr 
ioVRefNum 
ioFlFndrlnfo 
ioDirlD 
ioFlCrDat 
ioFlMdDat 



— > 
— > 



ProcPtr 

OSErr 

StringPtr 

Integer 

FInfo 

Longint 

Longint 

Longint 



A pointer to a completion routine. 
The result code of the function, 
A pointer to a pathname, 
A volume specification. 
Information used by the Finder. 
A directory ID. 

The date and time of creation. 

The date and time of last modification. 



DESCRIPTION 



The PBHSetFInf o function sets information (including the date and time of creation 
I^rmXaCandinforn.ationneededbytheFinder)about^^ 

pointed to by ioNamePtr on the volume specified by ioVRefNum. You should caU^ 
PB^S^^trinfo j^^t before PBHSetFInfo, so that the current informat^^^ 

the parameter block. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHSetFInf o is _HSetFileInf o. 



RESULT CODES 



noErr 

nsvErr 

ioErr 

bdNamErr 

fnfErr 

wPrErr 

fLckdErr 

vLckdErr 

dirNFErr 

afpAccessDenied 

af pOb j ectTypeErr 



0 No error 

-35 No such volume 

-36 I/O error 

-37 Bad filename 

-43 File not found 

-44 Hardware volume lock 

-45 File is locked 

-46 Software volume lock 

-120 Directory not found or incomplete pathname 
-5000 User does not have the correct access 
-5025 Object was a directory 



PBHSetFLock 



You can use the PBHSetFLock function to lock a file. 

FUNCTION PBHSetFLock (paramBlock: HParmBlkPtr; async: Boolean) 

OSErr ; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 
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Parameter block 



— > 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 




ioResult 


OSErr 


The result code of the function. 




ioNamePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volume specification. 


-> 


ioDirlD 


Longint 


A directory ID. 



DESCRIPTION 

The PBHSetFLock function locks the file with the name pointed to by ioNamePtr on 
the volume specified by ioVRe f Num. After you lock a file, all new access paths to that 
file are read-only. Access paths currently in use aren't affected. 

If the PBHGetVolParms function indicates that the volimie supports folder locking (that 
is, the bHasFolderLock bit of the vMAttrib field is set), you can use PBHSetFLock to 
lock a directory. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHSetFLock is _HSetFLock. 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


No such volume 


ioErr 


-36 


I/O error 


fnfErr 


-43 


File not fotmd 


wPrErr 


-44 


Hardware volume lock 


vLckdErr 


-46 


Software voltime lock 


dirNFErr 


-120 


Directory not found or incomplete pathname 


afpAccessDenied 


-5000 


User does not have the correct access to the file 


afpObjectTypeErr 


-5025 


Folder locking not supported by volume 



PBHRstFLock 



You can use the PBHRstFLock function to vmlock a file. 

FUNCTION PBHRstFLock (paramBlock: HParmBlkPtr; a sync : Boolean): 

OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

a sync A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 
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Parameter block 



— > 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<- 


ioResult 


OSErr 


The result code of the function. 




ioNamePtr 


StringPtr 


A pointer to a pathname. 




ioVRefNum 


Integer 


A volume specification. 


-> 


ioDirlD 


Longint 


A directory ID. 



DESCRIPTION 

The PBHRstFLock hmction unlocks the file with the name pointed to by ioNamePtr on 
the volume specified by ioVRef Num. Access paths currently in use aren't affected. 
If the PBHGetVolParms function indicates that the volume supports folder locking (that 
is, the bHasFolderLock bit of the vMAttrib field is set), you can use PBHRstFLock to 
unlock a directory. 

ASSEMBLY-IANGUAGE INFORMATION 

The trap macro for PBHRstFLock is _HRstFLock. 



RESUiT CODES 



noErr 


0 


nsvErr 


-35 


ioErr 


-36 


fnfErr 


-43 


wPrErr 


-44 


vLckdErr 


^6 


dirNFErr 


-120 


afpAccessDenied 


-5000 


af pOb j ectTypeErr 


-5025 



No error 

No such voliune 

I/O error 

File not found 

Hardware volume lock 

Software volume lock 

Directory not f oimd or incomplete pathname 
User does not have the correct access to the file 
Folder locking not supported by volume 



PBHRename 



You can use the PBHRename function to rename a file, directory, or volimie, 

FXJNCTION PBHRename (paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

par amBl ock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(false) execution. 
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Parameter block 

A pointer to a completion routine. 
The result code of the function. 
A pointer to a pathname. 
A volume specification, 
A pointer to the new name for the file. 
A directory ID. 

DESCRIPTION 

Given a pointer to the name of a file or directory in ioNamePtr, PBHRename changes it 
to the name pointed to by ioMisc. Given a pointer to a volimie name in ioNamePtr or 
a volume reference number in ioVRef Num, it changes the name of the volume to the 
name pointed to by ioMisc. 

Note 

If a file ID reference exists for the file being renamed, the file ID remains 
with the file. ♦ 

IMPORTANT 

You cannot use PBHRename to change the directory in which a file 
is located. ▲ 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro for PBHRename is _HRenanie. 



No error 
File directory full 
Volume is full 
No such volume 
1/ O error 
Bad filename 
File not found 
Hardware volume lock 
File is locked 
Software volume lock 
ChipHcate fQename and version 
No default volume 
Problem during rename 
Directory not found or incomplete pathname 
User does not have the correct access 

Moving Files or Directories 

The low-level HFS function PBCatMove allows you to move files and directories within 
a voliune. 
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-> 


ioCompletion 


ProcPtr 


<- 


ioResult 


OSErr 


-> 


ioNamePtr 


StringPtr 


-> 


ioVRefNum 


Integer 




ioMisc 


Ptr 


-> 


ioDirlD 


Longint 



RESULT CODES 



noErr 


0 


dirFulErr 


-33 


dskFulErr 


-34 


nsvErr 


-35 


ioErr 


-36 


bdNamErr 


-37 


fnf Err 


^3 


wPrErr 


-44 


fLckdErr 


-^5 


vLckdErr 


^6 


dupFNErr 


-48 


paramErr 


-50 


fsRnErr 


-59 


dirNFErr 


-120 


afpAccessDenied 


-5000 
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PBC^tMove 



You can use the PBCatMove function to move files or directories from one directory to 
another on the same volume. 

FXJNCTION PBCatMove (paramBlock: CMovePBPtr; async: Boolean): 

OSErr ; 

paramBlock A pointer to a catalog move parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(false) execution. 



Parameter block 



-> 


ioCompletion 


ProcPtr 


ir- 


ioResult 


OSErr 


-> 


ioNamePtr 


StringPtr 


— > 


ioVRefNum 


Integer 


-> 


ioNewName 


StringPtr 


-> 


ioNewDirlD 


Longint 



ioDirlD 



Longint 



A pointer to a completion routine. 
The result code of the function. 
A pointer to the name of the file or 
directory to be moved. 
A volume specification. 
A pointer to the name of the directory 
into which the file or directory is to 
be moved. 

The directory ID of the directory into 
which the file or directory is to be moved, 
if ioNewName is NIL. If ioNewName is 
not NIL, this is the parent directory ID of 
the directory into which the file or 
directory is to be moved. 
The directory ID of the file or directory to 
be moved. 



DESCRIPTION 



The PBCatMove fimction moves a file or directory from one directory to another within 
a volume. PBCatMove is strictly a file catalog operation; it does not actually change the 
location of the file or directory on the disk. 

The source file or directory should be specified by its volume, parent directory ID, and 
partial pathname. Pass a volume specification in ioVRefNum. Pass the parent directory 
ID in the ioDirlD field and a pointer to the partial pathname in the ioNamePtr field. 

The name of the directory into which the file or directory is to be moved is specified by 
the ioNewName field. If a valid directory name is provided for ioNewName, the 
destination directory's parent directory is specified in ioNewDirlD. However, you can 
specify NIL for ioNewName, in which case ioNewDirlD should be set to the directory 
ID of the destination directory itself. 

Note 

It is usually simplest to specify the destination directory by passing 
its directory ID in the ioNewDirlD field and by setting ioNewName 
to NIL. ♦ 
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The PBCatMove function cannot move a file or directory to another volume (that is, 
loVRef Num is used in specifying both the source and the destination). Also, you cannot 
use It to rename files or directories; to rename a file or directory use PBHRename. 
If a file ID reference exists for the file, the file ID reference remains with the moved file. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBCatMove are 
Trap macro Selector 



„HFSDispatch 



$0005 



RESULT CODES 



noErr 


0 


nsvErr 


-35 


ioErr 


-36 


bdNamErr 


-37 


f nfErr 


^3 


wPrErr 


-44 


fLckdErr 


-45 


vLckdErr 


-46 


dupFNErr 


-48 


paramErr 


-50 


badMovErr 


-122 


wrgVolTypErr 


-123 


afpAccessDenied 


-5000 



No error 

No such volume 

I/O error 

Bad filename or attempt to move into a file 

File not found 

Hardware volume lock 

Target directory is locked 

Software volume lock 

Duplicate filename and version 

No default volume 

Attempt to move into offspring 

Not an HFS volume 

User does riot have the correct access 



Maintaining Workin g Directories 

The File Manager provides several low-level functions that ajlow you to manipulate 
working directories. Working directories are used intemaUy by the File Manager; in 
general, your application should not create or directly access working directories. For 
more information about working directories, see "Working Directory Reference 
Numbers," begirming on page 2-26. 



PBOpenWD 

You can use tiie PBOpenWD function to create a working directory. 

FUNCTION PBOpenWD (paramBlock: WDPBPtr; async: Boolean): OSErr; 

paramBlock A pointer to a working directory parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 
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Parameter block 





ioCompletion 


ProcPtr 


<- 


ioResult 


OSErr 


-> 


ioNamePtr 


StringPtr 




ioVRefNum 


Integer 


-) 


ioWDProcID 


Longint 


-> 


ioWDDirlD 


Longint 



A pointer to a completion routine. 

The result code of the function. 

A pointer to a pathname. 

A volume specification. 

The working directory user identifier. 

The working directory's directory ID. 



The PBOpenWD function creates a working directory that correspond to .*ed«edory 
specified by ioVRefNum, ioWDDirlD, and ioWDProcID. (You caa also «P«^^ 
Sre ory iing a combination of partial pathname and directory ID.) PBOpenWD reU^ 
Tov^ef Num a working directory reference number that canbe used m subsequent Fde 

Manager calls. 

If a working directory having the specified user identifier already exists for A- ^^fied 
directory, no new working dLctory is opened; instead, the existmg workmg duectory 
;Z^e number is returned in ioVRefNum. If the specified directory already has a 
wor^g directory with a different user identifier, a new working directory reference 

number is returned. 

If the directory specified by the ioWDDirlD parameter is the volume's root directory, no 
lo^S is creat^; -tead, the volume reference number . returned m the 

i oVRe f Num parameter 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBOpenWD are 
Trap macro Selector 

_HFSDispatch $0001 



RESULT CODES 



noErr 

nsvErr 

fnfErr 

tmwdoErr 

afpAccessDenied 



0 No error 

-35 No such volume 

^3 No such directory 

-121 Too many working directories open 

-5000 User does not have the correct access 



PBCloseWD 



You can use the PBCloseWD function to dose a working directory. 

FUNCTION PBCloseWD (paramBlock : WDPBPtr; async: Boolean): OSErr; 

paramBlock A pointer to a vsrorking directory parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 
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Parameter block 



ioCompletion ProcPtr A pointer to a completion routine. 

<r- ioResul t OSEr r The result code of the function. 

ioVRefNum Integer A working directory reference 

number. 



DESCRIPTION 



The PBCloseWD function releases the working directory whose working directory 
reference number is specified in i o VRe f Num. 

Note 

If you specify a volume reference number in the ioVRef Num field, 
PBCloseWD does nothing. ♦ 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBCloseWD are 
Trap macro Selector 

_HFSDispatch $0002 



RESULT CODES 

noErr 0 No error 

nsvErr -35 No such volume 

rfNumErr -51 Bad working directory reference number 



PBGetWDInfo 



You can use the PBGetWDInfo function to get information about a working directory. 
FUNCTION PBGetWDInfo (paramBlock : WDPBPtr; async: Boolean): OSErr; 

paramBlock A pointer to a working directory parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<- 


ioResult 


OSErr 


The result code of the function. 


<r- 


ioNamePtr 


StringPtr 


A pointer to a pathname. 


<-> 


ioVRefNum 


Integer 


A volume specification. 


-> 


ioWDIndex 


Integer 


An index. 




ioWDProcID 


Longint 


The working directory user identifier. 




ioWDVRefNum 


Integer 


The volume reference number for the 




ioWDDirlD 




working directory. 




Longint 


The working directory's directory ID. 
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DESCRIPTION 

. ' The PBGetWDinf o function returns information about the specified working directory. 

The working directory can be specified either by its working directory reference number 
in ioVRef Hum (in which case the value of ioWDIndex should be 0), or by its index 
number in ioWDIndex. In the latter case, if the value of ibVRef Num is not 0, it's 
interpreted as a volume specification, and only working directories on that volume 
are indexed. 

The ioWDVRef Num field always returns the volume reference number. The ioVRefNum 
field contains a working directory reference number when a working directory reference 
number is passed in that field; otherwise, it returns a volimie reference number. 
PBGetWDinf o returns a pointer to the volume's name in the ioNamePtr field. You 
should pass a pointer to a Str31 value if you want that name returned. If you pass NIL 
in the ioNamePtr field, no volume name is returned. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and roxitine selector for PBGetWDinf o are 
Trap macro Selector 

_HFSDispatch $0007 



RESULT CODES 

noErr 0 No error 

nsvErr -35 No such volume 

rfNumErr -51 Bad working directory reference niunber 

Searching a Catalog 

The low-level HFS function PBCatSearch allows you to search a volume using a 
particular set of search criteria. 

PBCatSearch 

The PBCatSearch function searches a volume's catalog file using a set of search criteria 
that you specify. It builds a list of all files or directories that meet your specifications. 

FUNCTION PBCatSearch (paramBlock : HPantiBlkPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to a csParam variant of an HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 
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Parameter block 



DESCRIPTION 





ioCompletion 


ProcPtr 


ir- 


ioResult 


OSErr 


-> 


ioNamePtr 


StrinaPtT 


-> 


ioVRefNura 


Xnt GQsz" 


-> 


ioMatchPtr 


FSSpecArrayPtr 




i oReqMa t chCoun t 


Longint 


<- 


ioActMatchCount 


Longint 


-> 


ioSearchBits 


Longint 


-> 


ioSearchlnfol 


CInfoPBPtr 


-> 


ioSearchInfo2 


CInfoPBPtr 


-> 


ioSearchTime 


Longint 




ioCatPosition 


CatPositionRec 


-> 


ioOptBuf fer 


Ptr 


-» 


ioOptBufSize 


Longint 



A pointer to a completion routine. 
The result code of the function. 
A pointer to a volume name. 
A volume specification. 
A pointer to an array of matches. 
The maximum match count. 
The actual match count. 
Enable bits for fields in criteria 
records. 

The values and lower bounds. 
The masks and upper bounds. 
The maximum allowed search time. 
The current catalog position. 
A pointer to optional read buffer. 
The length of optional read buffer. 



The PBCatSearch function searches the volume you specify for files or directories 
that match two coordinated sets of selection criteria. PBCatSearch rehims (in the 
ioMatchPtr field) a pointer to an array of FSSpec records identifying the files and 
directories that match the criteria. 

If the catalog file changes between two timed calls to PBCatSearch (that is, when you are 
usmg ioSearchTime and ioCatPosition to search a volume in segments and 
the catalog file changes between searches), PBCatSearch returns a result code of 
catChangedErr and no matches. Depending on what has changed on the volume, 
ioCatPosi t ion might be invalid, most likely by a few entries in one direction or ' 
another. You can continue the search, but you risk either skipping some entries or reading 
some twice. 

When PBCatSearch has searched the entire volume, it rehims eof Err If it exits 
because it either spends the maximum time aUowed by ioSearchTime or finds the 
maximum number of matches aUowed by ioReqMatchCount, it returns noErr. You 
can specify a value of 0 in the ioSearchTime field to indicate that no time limit is to 
be enforced. 



SPEQAi CONSIDERATIONS 



Not aU volumes support the PBCatSearch function. Before you call PBCatSearch to 
search a particular volume, you should call the PBHGetVolParms hmction to determine 
whether that volume supports PBCatSearch. See page 2-147 for details on calling 
PBHGetVolParms. 

Even though AFP volumes support PBCatSearch, they do not support all of its feahires 
that are available on local volumes. These restrictions apply to AFP volumes: 

■ AFP volumes do not use the ioSearchTime field. Current versions of the AppleShare 
server software search for 1 second or until 4 matches are found. The AppleShare 
workstation software keeps requesting the appropriate number of matches until the 
server returns either the number specified in the ioReqMatchCount field or an error. 
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■ AFP volumes do not support both logical and physical fork lengths. If you request a 
- search using the length of a fork, the actual minimum length used is the smaDest of 

the values in the logical and physical fields of the ioSearchInf ol record and the 
actual maximum length used is the largest of the values in the logical and physical 
fields of the ioSearchInf o2 record, 

■ The f sSBNegate bit of the ioSearchBits field is ignored during searches of 
remote volumes that support AFP version 2.1. 

■ If the AFP server returns af pCatalogChanged, the catalog position record returned 
to your application (in the ioCatPosit ion field) is the same one you passed to 
PBCatSearch. You should clear the initialize field of that record to restart the 
search from the beginning. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBCatSearch are 
Trap macro Selector 

_HFSDispatch $0018 

RESULT CODES 



noErr 


0 


No error (entire catalog has not been searched) 


nsvErr 


-35 


Volume not foimd 


ioErr 


-36 


I/O error 


eof Err 


-39 


Logical end-of-file reached 


paramErr 


-50 


Parameters don't specify an existing volume 


extFSErr 


-58 


External file system 


wrgVolTypErr 


-123 


Volume is an MPS volume 


catChangedErr 


-1304 


Catalog has changed and catalog position record 






may be invalid 


afpCatalogChanged 


-5037 


Catalog has changed and search cannot be resumed 



SEE ALSO 

See "Searching a Volume" on page 2-38 for a description of how to use PBCatSearch. 

Exchanging the Data in Two Files 

The function PBExchangeFi les allows you to exchange the data in two files. 



PBExchangeFiles 



You can use the PBExchangeFiles function to exchange the data stored in two files on 
the same volume. 

FUNCTION PBExchangeFiles (paramBlock: HParmBlkPtr ; 

async: Boolean) : OSErr; 
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paramBlock A pointer to a basic HPS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

A pointer to a completion routine. 
The result code of the function. 
A pointer to a pathname. 
A volume specification. 
A pointer to the name of the destination file. 
The destination file's parent directory ID. 
The source file's parent directory ID. 

DESCRIPTION 

The PBExchangeFiles function swaps the data in two files by changing some of the 
information in the volume catalog and, if the files are open, in the file control blocks. The 
PBExchangeFiles function uses the file ID parameter block. 

You should use PBExchangeFiles to preserve the file ID when updating an existing 
file, in case the file is being tracked through its file ID. 

Typically, you use PBExchangeFiles after creating a new file during a safe save. 
You identify the names and parent directory IDs of the two files to be exchanged in 
the fields ioNamePtr, ioDestNamePtr, ioSrcDirlD, and ioDestDirlD. The 
PBExchangeFiles function changes the fields in the catalog entries that record the 
location of the data and the modification dates. It swaps both the data forks and the 
resource forks. 

The PBExchangeFiles function works on either open or dosed files. If either file is 
open, PBExchangeFi les updates any file control blocks associated with the file. 
Exchanging the contents of two files requires essentially the same access privileges as 
opening both files for writing. 

The PBExchangeFiles function does not require that file ID references exist for the 
files being exchanged. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBExchangeFi 1 es are 
Trap macro Selector 
_HFSDispatch $0017 



Parameter block 



— > 


ioCompletion 


ProcPtr 




ioResult 


OSErr 


— > 


ioNamePtr 


StringPtr 


-> 


ioVRefNum 


Integer 


-> 


ioDestNamePtr 


StringPtr 




ioDestDirlD 


Long In t 




ioSrcDirlD 


Longint 
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0 No error 

-35 Volume not found 

-36 I/O error 

-43 File not found 

-45 File is locked 

-46 Volume is locked or read-only 

-50 Fimction not supported by volume 

-53 Volume is offline 

-123 Not an-HFS volume 

1303 Files on different volumes 

5000 User does not have the correct access 

5025 Object is a directory, not a file 

5038 Source and destination are the same 



Shared Enviro nment Routines ^ 

The File Manager provides a number of routines that allow you to control access to files, 
directories, and volumes in a shared environment- The routines described in this section 
allow you to 

■ provide multiple users with read /write access to files 

■ lock and unlock portions of files opened with shared read/write permission 

■ manipulate share points on local shared volumes 

■ get and change the access privileges for directories 

■ mount remote volumes 

■ control login access 

■ access a hst of users and groups on the local file server 

Before using the routines described in this section, call the PBHGetVolParms 
function to see if the volume supports them. (The PBGetVolMountInf oSize, 
PBGetVolMountInf o, and PBVolumeMount routines are exceptions: you'll just 
have to make these calls and check the result code.) 

Opening Files Wh ile Denying Access ^ 

The PBHOpenDeny and PBHOpenRFDeny functions control file access modes and enable 
applications to implement shared read/write access to files. 



PB HOpenDeny 

You can use the PBHOpenDeny function to open a file's data fork using the access 
deny modes. 

FUNCTION PBHOpenDeny (paramBlock : HParmBlkPtr; async: Boolean): 

OSErr; 
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' noErr 
nsvErr 
ioErr 
fnfErr 
fLckdErr 
vLckdErr 
paramErr 
volOf f linErr 
wrgVolTypErr 
diffVolErr 
afpAccessDenied 
af pObj ectTypeErr 
a f pSameOb j ec t Er r 
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paramBlock A pointer to a basic HPS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 



-> 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


ir- 


ioResult 


OSErr 


The result code of the function. 


-> 


ioNamePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volume specification. 


<r- 


ioRefNum 


Integer 


The file reference number. 




ioDenyModes 


Integer 


Access rights data. 


-> 


ioDirlD 


Longint 


The directory ID. 



DESCRIPTION 

The PBHOpenDeny function opens a file's data fork with specific access rights specified 
in the ioDenyModes field. The file reference number is returned in ioRef Nxitn. 

The result code opWrErr is returned if you've requested write permission and you 
have already opened the file for writing; in that case, the existing file reference 
number is returned in ioRefNum. You should not use this reference number uidess 
your application originally opened the file. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHOpenDeny are 
Trap macro Selector 

_HFSDispatch $0038 



RESULT CODES 



noErr 


0 


No error 


tmfoErr 


-42 


Too many files open 


fnfErr 


-43 


File not found 


fLckdErr 


-AS 


File is locked 


vLckdErr 


-46 


Volume is locked or read-only 


opWrErr 


-49 


File already open for writing 


paramErr 


-50 


Function not supported by volume 


permErr ■ 


-54 


File is already open and carmot be opened using 
specified deny modes 


afpAccessDenied 


-5000 


User does not have the correct access to the file 


a f pDeny Con f I i c t 


-5006 


Requested access permission not possible 
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PBHOpenRFDeny 



You can use the PBHOpenRFDeny function to open a file's resource fork using the access 
deny modes. 

FUNCTION PBHOpenRFDeny (paramBlock: HParmBlkPtr; 

async: Boolean): OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 

A pointer to a completion routine. 
The result code of the function. 
A pointer to a pathname. 
A volume specification. 
The file reference number. 
Access rights data. 
The directory ID. 



-> 


ioCompletion 


ProcPtr 




ioResult 


OSErr 




ioNamePtr 


StringPtr 


-> 


ioVRefNum 


Integer 




ioRefNum 


Integer 


— > 


ioDenyModes 


Integer 


-> 


ioDirlD 


Longint 



DESCRIFnON 



The PBHOpenRFDeny function opens a file's resource fork with specific access rights. 
The path reference number is returned in ioRefNum. 

The result code opWrErr is returned if you've requested write permission and you 
have already opened the file for writing; in that case, the existing file reference 
number is returned in ioRefNum. You should not use this reference number unless 
your application originally opened the file. 



ASSEMBtY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHOpenRFDeny are 
Trap macro Selector 

_HFSDispatch $0039 



RESULT CODES 



noErr 


0 


tmfoErr 


-42 


fnfErr 


^3 


fLckdErr 


-45 


vLckdErr 


-46 


opWrErr 


-49 


paramErr 


-50 


permErr 


-54 


afpAccessDenied 


-5000 


a fpDeny Conflict 


-5006 



No error 

Too many files open 
File not foimd 
File is locked 

Voliune is locked or read-orUy 

File already open for writing 

Ftmction not supported by volimne 

File is already open and cannot be opened using 

specified deny modes 

User does not have the correct access to the file 
Requested access permission not possible 
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Locking and Unlocking File Ranges 

The File Manager provides several low-level routines that allov^ you to lock and unlock 
parts of files. These functions are ineffective when used on local HFS volumes unless 
local file sharing is enabled for those volumes. 



PBLockRange 



You can use the PBLockRange function to lock a portion of a file. 

FUNCTION PBLockRange (paramBlock : ParmBlkPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 

A pointer to a completion routine. 
The result code of the fimction. 
A file reference number. 
The nimiber of bytes in the range. 
The positioning mode. 
The positioning offset. 



3! 

CD 

to 





ioCompletion 


ProcPtr 


<- 


ioResult 


OSErr 


-> 


ioRefNum 


Integer 


-> 


ioReqCount 


Longint 


-> 


ioPosMode 


Integer 


-> 


ioPosOf f set 


Longint 



DESCRIPTION 

The PBLockRange function locks a portion of a file that was opened with shared 
read/write permission. The begirming of the range to be locked is determined by the 
ioPosMode and ioPosOf f set fields. The end of the range to be locked is determined 
by the begirming of the range and the ioReqCount field. For example, to lock the 
first 50 bytes in a file, set ioReqCount to 50, ioPosMode to f sFromStart, and 
ioPosOf f set to 0. Set ioReqCount to -1 to lock the maximum number of bytes from 
the position specified in ioPosOf f set. 

The PBLockRange function uses the same parameters as both PBRead and PBWrite; by 
calling it immediately before PBRead, you can use the information in the parameter 
block for the PBRead call. 

When you're finished with the data (typically after a call to PBWrite), be sure to call 
PBUnlockRange to free that portion of the file for subsequent PBRead calls. 



SPtQAL CONSIDERATIONS 

The PBLockRange function does nothing if the file specified in the ioRefNum field is 
open with shared read/write permission but is not located on a remote server volume 
or is not located under a share point on a sharable local volume. See "Locking and 
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Unlocking File Ranges" on page 2-50 for a simple way to determine whether calling 
; PBLockRange on an open file would in fact lock a range of bytes. 

▲ WARNING 

In system software versions 6.0.7 and earlier, specifying ioPosMode as 
f sFroniLEOF results in the wrong byte range being locked. A 

ASSEMBLY-LANGUAGE INFORMATION . 

The trap macro and routine selector for PBLockRange are 
Trap macro Selector 

_HFSDispatch $0010 



RESULT CODES 



noErr 


0 


ioErr 


-36 


fnOpnErr 


-38 


eof Err 


-39 


fLckdErr 


-45 


paramErr 


-50 


rfNumErr 


-51 


extFSErr 


-58 


volGoneErr 


-124 


afpNoMoreLocks 


-5015 


a f pRangeOver 1 ap 


-5021 



No error 
I/O error 
File not open 

Logical end-of-file reached 

File is locked by another user 

Negative ioReqCount 

Bad reference number 

External file system 

Server volume has been discormected 

No more ranges can be locked 

Fart of range is already locked 



PBUnlockRange 



You can use the PBUnlockRange function to unlock a portion of a file that was 
previously locked by a call to PBLockRange. 

FUNCTION PBUnlockRange (paramBlock : ParmBlkPtr; async: Boolean) 

OSErr; 

par amBl ock A pointer to a basic File Manager parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 



(FALSE) execution. 



Parameter block 



— > 


ioCompletion 


ProcPtr 




ioResult 


OSErr 


— > 


ioRefNum 


Integer 




ioReqCount 


Longint 


— > 


ioPosMode 


Integer 


— > 


ioPosOf f set 


Longint 



A pointer to a completion routine. 

The result code of the function. 

A file reference nvimber. 

The number of bytes in the range. 

The positioning mode. 

The positioning offset. 
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DESCRIPTION 

The PBUnlockRange function unlocks a portion of a file that you locked with 
PBLockRange. You specify the range by filling in the ioReqCount, ioPosMode, 
and ioPosOf f set fields as described in the preceding discussion of PBLockRange. 
The range of bytes to be tmlocked must be the exact same range locked by a previous 
call to PBLockRange. 

If for some reason you need to unlock a range whose beginning or length is unknown, 
you can simply close the file. When a file is closed, aD locked ranges held by the user 
are unlocked. 



SPECUL CONSIDERATIONS 

The PBUnlockRange function does nothing if the file specified in the ioRef Num field is 
open with shared read /write perrnission but is not located on a remote server volume or 
is not located under a share point on a local volume. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBUnlockRange are 
Trap macro Selector 

_HFSDispatch $0011 



RESULT CODES 



noErr 


0 


No error 


ioErr 


-36 


I/O error 


fnOpnErr 


-38 


File not open 


eofErr 


-39 


Logical end-of-file reached 


paramErr 


-50 


Negative ioReqCount 


rfNumErr 


-51 


Bad reference number 


extFSErr 


-58 


External file system 


volGoneErr 


-124 


Server voliune has been disconnected 


afpRangeNotLocked 


-5020 


Specified range was not locked 



Manipulating Share Points 

The PBShare and PBUnshare functions allow you to manipidate share points on local 
volumes. The PBGetUGEntry function lets you access the list of user and group names 
and IDs on the local server. 
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PBSh^e 



You can use the PBShare function to establish a local volume or directory as a 
share point. 

FUNCTION PBShare (paramBlock: HParmBlkPtr ; async: Boolean): OSErr; 
paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 



— > 



ioCompletion 
ioResult 
ioNamePtr 
ioVRefNum 
ioDirlD 



ProcPtr A pointer to a completion routine. 

OSErr The result code of the function. 

StringPtr A pointer to a pathname. 

Int eger A volume specification. 

Longint A directory ID. 



DESCRimON 

The PBShare function makes the directory specified by the ioNamePtr and ioDirlD. 
fields a share point. If ioNamePtr is NIL, then ioDirlD is the directory ID of the 
directory that is to become a share point. If ioNamePtr points to a partial pathname, 
ioDirlD is the parent directory of the directory to be shared. The ioVRefNum field can 
contain a volume reference number, a working directory reference number, a drive 
number, or 0 for the default volume. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBShare are 
Trap macro Selector 

_HFSDispatch $0042 



RESULT CODES 



noErr 


0 


No error 


tmfoErr 


-42 


Too many share points 


fnfErr 


-43 


File not f oimd 


dupFNErr 


-48 


Already a share point with this name 


paramErr 


-50 


Function not supported by volume 


dirNFErr 


-120 


Directory not found 


afpAccessDenied 


-5000 


This directory carmot be shared 


af pObj ectTypeErr 


-5025 


Object was a file, not a directory 


afpContainsSharedErr 


-5033 


The directory contains a share point 


a f pins ideShar edEr r 


-5043 


The directory is inside a shared directory 
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PBUnshare 



You can use ttie PBUnshare function to reverse the effects of PBShare. 

FUNCTION PBUnshare (paramBlock: HParmBlkPtr ; async: Boolean) : 

OSErr; 

paramBlock A pointer to a basic HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 



-> 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<- 


ioResult 


OSErr 


The result code of the function. 


~> 


ioNamePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volume specification. 




ioDirlD 


Longint 


A directory ID. 



DESCRIPTION 

The PBUnshare function makes the share point specified by the ioNamePtr and 
ioDirlD fields imavailable on the network. If ioNamePtr is NIL, then ioDirlD is 
the directory ID of the directory that is to become unavailable. If ioNamePtr points 
to a partial pathname, ioDirlD is the parent directory of the directory to become 
unavailable. The ioVRefNum field can contain a yolume reference number, a working 
directory reference number, a drive number, or 0 for the default voivune. 

ASSEMBLY-LANGUAGE INFORMATION * 

The trap macro and routine selector for PBUnshare are 
Trap macro Selector 

_HFSDispatch $0043 



RESULT CODES 



noErr 


0 


No error 


fnf Err 


-43 


File not fotmd 


paramErr 


-50 


Function not supported by volume 


dirNFErr 


-120 


Directory not foimd 


a f pOb j ec tTypeEr r 


-5025 


Object was a file, not a directory; or, this directory is 
not a share point 
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PBGetUGEntry 



You can use the PBGetUGEntry function to get a list of user and group entries from the 
local file server 

FUNCTION PBGetUGEntry {paramBlock : HParmBlkPtr ; async: Boolean): 

OSErr ; 

paramBlock A pointer to an ob j Pa ram variant of an HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 


ir- 


ioResult 


OSErr 


The result code of the function. 


-> 


ioObjType 


Integer 


A function code. 




ioObjWamePtr 


Ptr 


A pointer to the returned user/ group name. 


<-> 


ioObjID 


Longint 


A user/group ID. 



DESCRIPTION 

The PBGetUGEntry function returns the name and ID of the user or group whose name 
is alphabetically next to that of the user or group whose ID is contained in the ioOb j ID 
field. You can enumerate the users or groups in alphabetical order by setting ioObj ID to 
0 and then repetitively calling PBGetUGEntry with the same parameter block until the 
result code f nf Err is returned. 

You specify whether you want information about users or groups by setting the 
ioObjType field to the desired value. Set IoObjType to 0 to receive the next user 
entry; set it to -1 to receive the next group entry. 

Tlie user or group name is returned as a Pascal string pointed to by ioObj Name Ptr. 
The maximum size of the string is 31 characters, preceded by a length byte. If you set 
ioObjNamePtr to NIL, no name is returned. 

If you set ioOb j ID to 0, PBGetUGEntry returns information about the user or group 
known to the local server whose name is alphabetically first. If the value of ioObj ID is 
not 0, PBGetUGEntry returns information about the user or group whose name follows 
immediately in alphabetical order that of the user or group having that ID. 

ASSEMBIY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBGetUGEntry are 

Trap macro Selector 

„HFSDispatch $0044 

RESULT CQDES 

noErr 0 No error 

f nf Err -43 No more users or groups 

paramErr -50 Fimction not supported; or, ioObj ID is negative 
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Controlling Directory Access 

The PBHGetDirAccess and PBHSetDirAccess functions control privileges for 
individual directories. 

PBHGetDirAccess 



You can use the PBHGetDirAccess function to get the access control infonnation for 
a directory. 

FUNCTION PBHGetDirAccess {paramBlock: HParmBlkPtr; 

async: Boolean) : OSErr; 

paramBlock A pointer to an HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 





ioCompletion 


ProcPtr 


A pointer to a completion routine. 




ioResult 


OSErr 


The result code of the fimction. 




ioNamePtr 


StringPtr 


A pointer to a pathname. 


— > 


ioVRefNum 


Integer 


A volume specification. 


<— 


ioACOwnerlD 


Longint 


The owner ID. 


<r- 


ioACGroupID 


Longint 


The group ID. 




ioACAccess 


Longint 


The access rights. 


— > 


ioDirXD 


Longint 


The directory ID. 



DESCRIPTION 

The PBHGetDirAccess returns access control information for the specified directory. 
On output, the ioACOvmef ID field contains the ID of the directory's owner, and the 
ioACGroupID field contains the directory's primary group. The directory's access rights 
are encoded in the ioACAccess field. See "Directory Access Privileges," beginning on 
page 2-18, for a description of the ioACAccess field. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHGetDirAccess are 
Trap macro Selector 

_HFSDispatch $0032 



RESULT CODES 



noErr 0 

fnfErr ^3 

paraniErr -50 

afpAccessDenied -5000 



No error 

Directory not fotmd 

Function not supported by volume 

User does not have the correct access to the directory 
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PBHget DirAccess 

You can use the PBHSetDir Access function to change the access control information 
for a directory. 

FUNCTION PBHSetDirAccess (paramBlock: HParmBlkPtr ; 

async: Boolean): OSErr; 

paramBlock A pointer to an HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 



-> 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 




ioResult 


OSErr 


The result code of the function. 




ioNamePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volume specification. 


-> 


ioACOwnerlD 


Longint 


The ow^ner ID. 


-> 


ioACGroupID 


Longint 


The group ID. 




ioACAccess 


Longint 


The access rights. 




ioDirlD 


Longint 


The directory ID. 



DESCRimON 

The PBHSetDirAccess function allows you to change the access rights to the specified 
directory. The ioACAccess field contains the directory's access rights. You cannot set 
the owner or user rights bits of the ioACAccess field directly (if you try to do this, 
PBHSetDirAccess returns the result code paramErr). See "Directory Access 
Privileges/' begiiming on page 2-18, for a description of the ioACAccess field. 

To change the owner or group, you should set the ioACOwnerlD or ioACGroupID field 
to the appropriate ID. You must be the owner of the directory to change the owner or 
group ID. A guest on a server can manipulate the privileges of any directory owned by 
the guest. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHSetDirAccess are 
Trap macro Selector 

_HFSDispatch $0033 

RESULT CODES 



noErr 


0 


No error 


fnfErr 


-43 


Directory not found 


vLckdErr 


-46 


Volume is locked or read-only 


paramErr 


-50 


Parameter error 


afpAccessDenied 


-5000 


User does not have the correct access to the directory 


af pOb j ectTypeErr 


-5025 


Object is a file, not a directory 
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Mounting Volumes 

The File Manager provides three hinctions that allow your application to record the 
mounting information for a volume and then to moimt the volume later. The program- 
matic mounting functions store the mounting information in a structure called the 
AFPVolMountlnf o record. The programmatic mounting functions use the ioParam 
variant of the ParamBlockRec record. 

In general, it is easier to mount remote volumes by creating and then resolving alias 
records that describe those volumes. The Alias Manager displays the standard user 
interface for user authentication when resolving alias records for remote volumes. As 
a result, the routines described in this section are primarily of interest for applications 
that need to mount remote volumes with no user interface or with some custom 
user interface. 

Note 

All the functions described in this section execute synchronously. You 
should not call them at interrupt time. ♦ 



PBGetVolMountlnfoSize 



You use the PBGetVolMountlnfoSize function to determine how much space to 
allocate for a volume moimting information record. 



FUNCTION PBGetVolMountlnfoSize (paramBlock: ParmBlkPtr) : OSErr; 



paramBlock A pointer to a basic File Manager parameter block. 
Parameter block 



— > ioCompletion Longint 

<— ioResult OSErr 

— > ioVRefNum Integer 

-> ioBuffer Longint 



A pointer to a completion routine. 

The fujictioh's result code. 

A volume specification. 

A pointer to storage for size. 



DESCRIPTION 

For a specified volimie, the PBGetVolMountlnfoSize function provides the size 
of the record needed to hold the volume's motmting information. The ioBuffer 
field is a pointer to the size information, which is of type Integer (2 bytes). If 
PBGetVolMountlnfoSize returns noErr, that integer contains the size of the 
volume moxmting information record. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBGetVolMountlnfoSize are 
Trap macro Selector 

_HFSDispatch $003F 
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RESULT CODES 



noErr 
nsvErr 
paramErr 
extFSErr 



0 No error 
-35 Volume not found 
-50 Parameter error 

-58 External fUe system error; typically, function 
is not available for that volume 



PBG etVolMountInf o 



After ascertaining the size of the record needed and allocating storage, you can use the 
PBGetVolMountInf o hmction to retrieve a record containing all the information 
needed to mount the volume, except for passwords. You can later pass this record to the 
PBVolumeMount function to mount the volume. 

FUNCTION PBGetVolMountInf o (paramBlock : ParmBlkPtr) : OSErr; 
paramBlock A pointer to a basic File Manager parameter block. 



Parameter block 

— > ioCompletion Longint 

ioResult OSErr 

ioVRefNum Integer 

ioBuffer Longint 



A pointer to a completion routine. 

The function's result code. 

A volume specification. 

A pointer to moimting information. 



DESCRIFnON 



The PBGetVolMountInf o hmction places the mounting information for a specified 
volume into the buffer pointed to by the ioBuffer field. The mounting information for 
an AppleShare volume is stored as an AFP mounting record. The length of the buffer is 
specified by the value pointed to by the ioBuf f er field in a previous call to 
PBGetVolMount Infos i ze. 

The PBGetVolMountInf o hmction does not return the user password or volume 
password in the AFPVolMountInf o record. Your appHcation should solicit 
these passwords from the user and fill in the record before attempting to mount the 
remote volume. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBGetVolMountInf o are 
Trap macro Selector 

_HFSD.ispatch $0040 
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RESULT CODES 



noErr 
nsvErr 
paramErr 
extFSErr 



0 No error 
-35 Volume not found 
-50 Parameter error 

^58 External file system error; typically, function is not 
available for tfiat volume 



PBVolumeMount 



You can use the PBVolumeMount function to mount a volume, using either the 
information returned by the PBGetVolMountInf o function or a structure filled in by 
your application. 

FUNCTION PBVolumeMount (paramBlock: ParmBlkPtr) : OSErr; 
paramBlock A pointer to a basic File Manager parameter block. 



I 

CD 



ZJ 
CD 



Parameter block 

-> ioCompletion 

f- ioResult 

<r- ioVRefNum 

-> ioBuffer 



Long In t A pointer to a completion routine. 

OSErr The function's result code. 

Int eger A volume reference number. 

Longint A pointer to mounting information. 



DESCRIPTION 

The PBVolumeMount fimction mounts a volume and returns its volume reference 
number. If you're mounting an AppleShare volume, place the volume's AFP mounting 
information record in the buffer pointed to by the ioBuffer field. 

The PBGetVolMountInf o function does not return the user and volume passwords; 
they're retvuned blank. Typically, your application asks the user for any necessary 
passv^ords and fills in those fields just before calling PBVolumeMount. If you v^ant to 
movmt a volume with guest status, pass an empty string as the user password. 

If you have enough information about the voltune, you can fill in the moimting record 
yourself and call PBVolumeMount, even if you did not save the motmting information 
while the volume was mounted. To motmt an AFP volim\e, you must fill in the record 
with at least the zone name, server name, user name, user password, and volume 
password. You can lay out the fields in any order within the data field, as long as you 
specify the correct offsets. 



SPECIAL CONSIDERATIONS 

The File Sharing workstation software introduced in system software version 7.0 does 
not currently pass the volume password. The AppleShare 3.0 workstation software does, 
however, pass the volume password. 
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AFP volumes currently ignore the user authentication method passed in the uamType 
' field of the volume mounting information record whose address is passed in ioBuf f er. 
The most secure available method is used by default, except when a user mounts the 
volume as <Guest> and uses the kNoUserAuthentication authentication method. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBVolumeMount are 
Trap macro Selector 

_HFSDispatch $0041 



RESULT CODES 



noErr 0 

notOpenErr -28 

nsvErr -35 

paramErr -50 



extFSErr -58 



memFullErr -108 

afpBadUAM -5002 

afpBadVersNum -5003 

afpNoServer -5016 

a f pUs erNot Au th -5023 

afpPwdExpired -5042 

a f pBadDi r I DType -5060 
afpCantMountMoreSrvrs -5061 

a f pAl ready Moun t ed -5062 

afpSameNodeErr -5063 



No error 

AppleTalk is not open 
Voliune not foimd 

Parameter error; typically, zone, server, and 
volume name combination is not valid or not 
complete, or the user name is not recognized 
External file system error; typically, file system 
signature was not recognized, or function is 
not available for that volume 
Not enough memory to create a new volume 
control block for mounting the voliune 
User authentication method is imknown 
Workstation is using an AR^ version that the 
server doesn't recognize 
Server is not responding 
User authentication failed (usually, password 
is not correct) 

Password has expired on server 

Not a fixed directory ID volume 

Maximum number of volumes has 

been moimted 

Volume already moimted 

Attempt to log on to a server running on the 

same machine 



Controlling Login Access 

You can use the functions PBHGetLoglnInf o, PBHMapID, and PBHMapName to 
get information about the login method and the recognized users and groups on a 
particular machine. 
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PBHGetLoglnlnfo 



You can use the PBHGetLoglnlnfo function to determine the login method used to log 
on to a particular shared volume. 

FUNCTION PBHGetLoglnlnfo (paramBlock: HParmBlkPtr; 

async: Boolean): OSErr; 

paramBlock A pointer to an obj Par am variant of the HFS parameter block, 
async 



A Boolean value that specifies asynchronous (TRUE) or synchronous 
(FALSE) execution. 



Parameter block 



loCompletion 
ioResult 
ioVRefNum 
ioObjType 
ioObjNamePtr 



ProcPtr 

OSErr 

Integer 

Integer 

Ptr 



A pointer to a completion routine. 

The result code of the function. 

The volume specification. 

The login method. 

A pointer to the user name. 



DESCRIPTION 



The PBHGetLoglnlnfo function rehims the method used for login and the user name 
specified at login time for the volume specified by the ioVRefNum field. The login user 
name is rehimed as a Pascal string in ioObjNamePtr. The maximum size of the user 
name is 31 characters. The login method type is returned in the ioOb j Type field. These 
values are recognized. 



CONST 

kNoUserAuthentication = 1 

kPassword = 2 

kEncrypt Password = 3 

kTwoWay Encrypt Password = 6 



{no password} 
(8-byte password} 
{encrypted 8-byte password} 
{two-way random encryption} 



Values in the range 7-127 are reserved for fuhire use by Apple Computer, Inc. Values in 
the range 128-255 are available to your application as user-defined values. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHGetLoglnlnfo are 
Trap macro Selector 

_HFSDispatch $0031 



RESULT CODES 



noErr 

nsvErr 

paramErr 



0 

-35 
-50 



No error 

Specified volume doesn't exist 
Function not supported by volume 
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PBHMapID 



You can use the PBHMapID function to determine the name of a user or group if you 
know the user or group ID, 

FUNCTION PBHMapID (paramBlock : HParmBlkPtr; async: Boolean): 

OSErr ; 

paramBlock A pointer to an ob j Param variant of the HFS parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 



(FALSE) execution. 



Parameter block 

ioCompletion 
ioResult 
ioNamePtr 
ioVRefNum 
ioObjType 
ioObjNamePtr 
ioObjID 



-> 
<- 



ProcPtr 

OSErr 

StringPtr 

Integer 

Integer 

Ptr 

Longint 



A pointer to a completion routine. 

The result code of the f unction. 

A pointer to a pathname. 

A volume specification. 

The login method. 

A pointer to the user/group name. 

The user/ group ID. 



DESCKIPTION 



The PBHMapID function rehims the name of a user or group given its unique ID, The 
ioOb j ID field contains the ID to be mapped. (AppleShare uses the value 0 to signify ^ 
<Any User>.) The ioObjType field is the mapping function code; its value is 1 if you're 
mapping a user ID to a user name or 2 if you're mapping a group ID to a group name. 
The name is returned in ioObjNamePtr; the maximum size of the name is 31 characters 
(preceded by a length byte). 

Because user and group IDs are interchangeable under AFP 2.1 and later volumes, you 
might not need to specify a value in the ioObjType field. 



ASSEMBtY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHMapID are 
Trap macro Selector 

_HFSDispatch $0034 



RESULT CODES 

noErr 0 No error 

f nf Err -43 Unrecognizable owner or group name 

paramErr -50 Fxmction not supported by volume 
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PBHMapName 



You can use the PBHMapName function to determine the user ID or group ID from a user 
or group name. 

FUNCTION PBHMapName (paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

paramBlock A pointer to an ob j Param variant of the HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(false) execution. 

Parameter block 



-> 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<- 


ioResult 


OSErr 


The result code of the function. 




ioNamePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum * 


Integer 


A volume specification. 


-> 


ioObjType 


Integer 


The login method. 




ioObj NamePtr 


Ptr 


A pointer to the user/ group name. 




ibObjID 


Longint 


The user /group ID. 



DESCRIPTION 

Given a name, the PBHMapName function retvims the corresponding unique user ID 
or group ID. The name is passed as a string in ioObj Name Ptr. If NIL is passed, the ID 
returned is always 0. The maximum size of the name is 31 characters. The ioOb j Type 
field is the mapping function code; its value is 3 if you're mapping a user name to a user 
ID or 4 if you're mapping a group name to a group ID. On exit, ioObj ID contains the 
mapped ID. 

Because user and group IDs are interchangeable under AFP 2.1 and later volumes, you 
might need to set the ioObjType field to determine v/hich database (user or group) to 
search first. If both a user and a group have the same name, this field determines which 
kind of ID you receive. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHMapName are 

Trap macro Selector 

_HFSDispatch $0035 

RESULT CODES 

noErr 0 No error 

f nf Err -43 Unrecognizable owner or group name 

paramErr -50 Function not supported by volume 
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Copying an d Moving Files ^ ^ 

The File Manager provides two shared environment routines — PBHCopyFi le and 
PBHMoveRename— that allow you to copy and move files. These routines are especially 
useful when you want to copy or move files located on a remote volume, because they 
allow you to forgo transmitting large amounts of data across a network. These routines 
are used internally by the Finder; most applications do not need to use them. 
If you do want to use PBHCopyFi le or PBHMoveRename, you should first call 
PBHGetVolParms to see whether the target volume supports these routines. 

PBHCopyFile 

You can use the PBHCopyFile function to duplicate a file and optionally to rename it. 

FUNCTION PBHCopyFile (paramBlock: HParmBlkPtr ; async: Boolean): 

OSErr; 

paramBlock A pointer to a copy Par am variant of the HFS parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 



— > 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<— 


ioResult 


OSErr 


The result code of the function. 


— > 


ioNaraePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volim\e specification. 


-> 


ioDstVRefNum 


Integer 


Destination volume identifier. 


— > 


ioNewName 


Ptr 


A pointer to the destination 
pathname (may be NIL). 


— > 


ioCopyName 


Ptr 


A pointer to the file's new name 
(may be NIL). 




ioNewDirlD 


Longlnt 


The destination directory ID. 


— > 


ioDirlD 


Longint 


The source directory ID, 



DESCRimON 

The PBHCopyFile function duplicates a file on the specified volume and optionally 
renames it. It is an optional call for AppleShare file servers. Your application shoxild 
examine the information returned by the PBHGetVolParms function to see if the 
voliune supports PBHCopyFile. 

For AppleShare file servers, the source and destination pathnames must indicate the 
same file server; however, the parameter block may specify different source and 
destination volumes on that file server. A useful way to tell if two file server volumes are 
on the same file server is to call the PBHGetVolParms function for each volume and 
compare the server addresses returned. The server opens source files with read/ deny 
write enabled and destination files with write/deny read and write enabled. 
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You specify the source file with the ioVRef Num, ioDirlD, and ioNamePtr fields. You 
specify the destination directory with the ioDs tVRe f Num, ioNewDirlD, and 
ioNewName fields. If ioNewName is NIL, the destination directory is the directory 
having ID ioNewDirlD on the.specified volume; if ioNewName is not NIL, the 
destination directory is the directory having the partial pathname pointed to by 
ioNewName in the directory having ID ioNewDirlD on the specified volume. 

The ioCopyName field may contain a pointer to an optional string to be used in copying 
the file; if it is not NIL, the file copy is renamed to the name specified in ioCopyName. 
The string pointed to by ioCopyName must be a filename, not a partial pathname. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHCopyFi le are 
Trap macro Selector 

_HFSDispatch $0036 



RESULT CODES 



noErr 


0 


dskFulErr 


-34 


fnfErr 


-43 


vLckdErr 


-46 


f BsyErr 


-47 


dupFNErr 


-48 


paramErr 


-50 


wrgVolTypErr . 


-123 


afpAccessDenied 


-5000 


afpDenyConf lict 


-5006 


af pOb j ectTypeErr 


-5025 



No error 

Destination volume is full 

Source file not found, or destination directory does 
not exist 

Destination volume is read-only 

The source or destination file could not be opened 

with the correct access modes 

Destination file already exists 

Function not supported by volimie 

Function not supported by volimie 

The user does not have the right to read the source or 

write to the destination 

The source or destination file could not be opened 
with the correct access modes 
Source is a directory 



PBHMoveRename 



You can use the PBHMoveRename function to move a file or directory and optionally to 
rename it. 

FUNCTION PBHMoveRename (paramBlock: HParmBlkPtr; 

async: Boolean): OSErr; 

paramBlock Apointer to a copy Param variant of the HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 
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Parameter block 



-> 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<- 


ioResult 


OSErr 


The result code of the function. 


-> 


ioNamePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volume specification. 




ioNewName 


Ptr 


A pointer to the destination 
pathname (may be NIL). 


-> 


ioCopyName 


Ptr 


A pointer to the file's new name 
(may be NIL). 




ioNewDirlD 


Longint 


The destination directory ID. 


-> 


ioDirlD 


Longint 


The source directory ID. 



DESCRIFHON 

The PBHMoveRename function allows you to move (not copy) a file or directory and 
optionally to rename it. The source and destination pathnames must point to the same 
file server volume. 

You specify the source file or directory with the ioVRefNum, ioDirlD, and ioNaraePtr 
fields. You specify the destination directory with the ioNewDirlD and ioNewName 
fields. If ioNewName is NIL, the destination directory is the directory having ID 
ioNewDirlD on the specified volume; if ioNewName is not NIL, the destination 
directory is the directory having the partial pathname pointed to by ioNewName in 
the directory having lD ioNewDirlD on the specified volume. 

The ioCopyName field may contain a pointer to an optional string to be used in copying 
the file or directory; if it is not NI L, the moved object is renamed to the name specified 
in ioCopyName. The string pointed to by ioCopyName must be a filename, not a 
partial pathname. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBHMoveRename are 
Trap macro Selector 

„HFSDispatch $0037 



RESULT CODES 



noErr 


0 


No error 


fnfErr 


-43 


Source file or directory not found 


fLckdErr 


-45 


File is locked 


vLckdErr 


-46 


Destination volume is read-only 


dupFNErr 


-48 


Destination already exists 


paramErr 


-50 


Function not supported by voltune 


badMovErr 


-122 


Attempted to move directory into offspring 


afpAccessDenied 


-5000 


The user does not have the right to move the file 






or directory 
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File ID Routines 

The File Manager provides several routines that allow you to track fUes using file IDs. 
These routines use the f idParam variant of the HFS parameter block. 

Note 

Most applications do not need to use these routines. In general you 
should track files using alias records, as described in the chapter "Alias 
Manager" in this book. The Alias Manager uses file IDs internally as 
part of its search algorithms for finding the target of an alias record. ♦ 

Resolving File ID References 

You can find the target of a file ID reference by calling the PBResolveFilelDRef 
fimction. 



PBResolveFilelDRef 



You can use the PBRes.olveFilelDRef hmcfion to retrieve the filename and parent 
directory ID of the file with a specified file ID. 

FUNCTION PBResolveFilelDRef (paramBlock : HParmBlkPtr; 

async: Boolean): OSErr; 

paramBlock A pointer to an f idParam variant of the HFS parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 



(FALSE) execution. 



Parameter block 

-> ioCompletion 
<- ioResult 
^ ioNamePtr 
ioVRefNum 
<~ ioSrcDirlD 
-> ioFilelD 



ProcPtr 

OSErr 

StringPtr 

Integer 

Longint 

Longint 



A pointer to a completion routine. 
The result code of the function. 
A pointer to a filename. 
A volume specification. 
The file's parent directory ID. 
A file ID. 



DESCRIPTION 



The PBResolveFilelDRef function returns the filename and patent directory ID of the 
file referred to by file ID in the ioFilelD field. It places the filename in the string 
pointed to by the ioNamePtr field and the parent directory ID in the ioSrcDirlD field. 
If the name string is NIL, PBResolveFilelDRef returns only the parent directory ID. If 
the name string is not NIL but is only a volume name, PBResolveFilelDRef ignores 
the value in the ioVRefNum field, uses the volume name instead, and overwrites the 
name string with the filename. A return code of f idNotFoundErr means that the 
specified file ID reference has become invahd, either because the file was deleted or 
because the file ID reference was destroyed by PBDeleteFilelDRef . 
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ASSEMBLY-LANGUAGE INFORMATION 

i The trap macro and routine selector for PBResolveFilelDRef are 
Trap macro Selector 

_HFSDispatch $0016 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


Volume not found 


ioErr 


-36 


I/O error 


fnfErr 


-43 


File not found 


paramErr 


-50 


Function not supported by volume 


volOf f linErr 


-53 


Volume is offline 


extFSErr 


-58 


External file system 


wrgVolTypErr 


-123 


Not an HPS volume 


f idNotFoundErr 


-1300 


File ID not foimd 


notAFileErr 


-1302 


Specified file is a directory 


afpAccessDenied 


-5000 


User does not have the correct access 


af pOb j ectTypeErr 


-5025 


Specified file is a directory 


afpIDNotFound 


-5034 


File ID not found 


afpBadlDErr 


-5039 


File ID not found 



Creating and Deleting File ID References 

You can create and delete file ID references using the functions PBCreateFilelDRef 
and PBDeleteFilelDRef . 

Note 

Most applications should not directly create or delete file ID references. ♦ 



PBCreateFilelDRef 

Use the PBCreateFilelDRef function to establish a file ID reference for a file. 

FUNCTION PBCreateFilelDRef (paramBlock: HParmBlkPtr; 

async: Boolean) : OSErr; 

parainBlock A pointer to an f idParam variant of the HFS parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 

Parameter block 



— > 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<- 


ioResult 


OSErr 


The result code of the function. 


-> 


ioNamePtr 


StringPtr 


A pointer to a filename. 




ioVRefNum 


Integer 


A voltune specification. 


->■ 


ioSrcDirlD 


Long In t 


The file's parent directory ID. 


f- 


ioFilelD 


LongInt 


A file ID. 
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DESCRIPTION 

Given a volume reference number, filename, and parent directory ID, the 
PBCreateFilelDRef function creates a record to hold the name and parent directory 
ID of the specified file. PBCreateFilelDRef places the file ID in the ioFilelD field. 
If a file ID reference aheady exists for the file, PBCreateFilelDRef supplies the file 
ID but returns the result code f idExists. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBCreateFilelDRef are 
Trap macro Selector 

_HFSDispatch $0014 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


Volume not foimd 


ioErr 


-36 


I/O error 


fnfErr 


^3 


File not found 


wPrErr 


-44 


Hardware volume lock 


vLckdErr 


-A6 


Software volume lock 


paramErr 


-50 


Function not supported by volume 


volOf f linErr 


-53 


Volume is offline 


extFSErr 


-58 


External file system 


wrgVolTypErr 


-123 


Not an HFS volume 


f idExists 


-1301 


File ID already exists 


notAFileErr 


-1302 


Specified file is a directory 


afpAccessDenied 


-5000 


User does not have the correct access 


af pOb j ectTypeErr 


-5025 


Specified file is a directory 


afpIDExists 


-5035 


File ID already exists 



PBDeleteFilelDRef 



You can use the PBDeleteFilelDRef function to delete a fUe ID reference. 

FUNCTION PBDeleteFilelDRef (paramBlock: HParmBlkPtr; 

async: Boolean): OSErr; 

paramBlock A pointer to an f idParam variant of the HFS parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 





ioCompletion 


ProcPtr 


<— 


ioResult 


OSErr 




ioNamePtr 


StringPtr 


-> 


ioVRefNum 


Integer 




ioFilelD 


Longint 



A pointer to a completion routine. 
The result code of the function. 
A pointer to a filename. 
A volume specification. 
A file ID. 
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"description 

The PBDeleteFilelDRef function invalidates the specified file ID reference on the 
volume specified by ioVRef Num or ioNamePtr. After it has invalidated a file ID 
reference, the File Manager can no longer resolve that ID reference to a filename ar\d 
parent directory ID. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBDeleteFilelDRef are 
Trap macro Selector 

_HFSDispatch $0015 

RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


Volume not found 


ioErr 


-36 


I/O error 


f nfErr 


-43 


File not found 


wPrErr 


-44 


Hardware volume lock 


vLckdErr 


-46 


Software volume lock 


paramErr 


-50 


Function not supported by volume 


volOf f lihErr 


-53 


Volume is offline 


extFSErr 


-58 


External file system 


wrgVolTypErr 


-123 


Function is not supported by volume 


f idNot FoundErr 


-1300 


File ID not found 


afpAccessDenied 


-5000 


User does not have the correct access 


af pOb j ectTypeErr 


-5025 


Specified file is a directory 


afpIDNotFound 


-5034 


File ID not found 



Foreign File System Routines 

The File Manager provides several routines that allow you to obtain and set privilege 
information on foreign file systems. The PBGetForeignPrivs and PBSetForeignPrivs 
fimctions allow your application or shell program to communicate with a foreign file 
system about its native access-control system. These functions retrieve and set access 
permissions on the foreign file system, using a f oreignPr i vParam variant of the HFS 
parameter block. 



PB G e tForeignPri vs 



You can use the PBGetForeignPrivs function to determine the native access-control 
information for a file or directory stored on a voliune managed by a foreign file system. 

FUNCTION PBGetForeignPrivs (paramBlock: HParmBlkPtr; 

async: Boolean) : OSErr; 

2-232 Rle Manager Reference 



TIVO-408682 



CHAPTER 2 



RIe Manager 



paramBlock A pointer to a f oreignPr ivParam variant of the HFS parameter block, 
async A Boolean value that specifies asynchronous (TRUE) or synchronous 



(FALSE) execution. 



Parameter block 



ioCompletion 

ioResult 

ioNamePtr 

ioVRefNum 

ioForeignPrivBuf far 

ioForeignPrivReqCount 
ioForeignPrivActCount 
ioForeignPrivDirlD 
ioForeignPrivInfol 

ioFpreignPrivInfo2 • 

ioForeignPrivInfo3 

ioForeignPrivInfo4 



ProcPtr 

OSErr 

StringPtr 

Integer 
Ptr 

Longlnt 
Longint 
Integer 
Longlnt 

Longlnt 

Longlnt 

Longlnt 



A pointer to a completion routine. 

The result code of the function. 

A pointer to a file or 

directory name. 

A volume specification. 

A pointer to the privilege 

information buffer. 

The size allocated for the buffer. 

The amount used in buffer. 

The parent directory ID. 

Information specific to 

privilege model. 

Information specific to 

privilege model. 

Information specific to 

privilege model. 

Information specific to 

privilege model. 



DESCRIPTION 



The PBGetForeignPrivs funcHon retrieves access information for a file or directory" 
on a volume managed by a file system that uses a privilege model different from the AFP 
model. See "Privilege Information in Foreign File Systems" on page 2-20 for a more 
coiriplete explanation of access-control privileges. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBGetForeignPrivs are 
Trap macro Selector 
_HFSDispatch $0060 



RESULT CODES 



"oErr 0 No error 

^sv5:rr -35 Volume not found 

paramErr _50 



Volume is HFS or MFS (that is, it has no foreign 
privilege model), or foreign voliune does not 
support these calls 
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PBSefforeignPrivs — 

You can use the PBSetForeignPrivs function to change the native access-control 
information for a file or directory stored on a volume managed by a foreign file system. 

FUNCTION PBSetForeignPrivs (paramBlock: HParmBlkPtr; 

async: Boolean): OSErr; 

paramBlock A pointer to a f oreignPr ivParam variant of the HFS 
parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 






— > 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<- 


ioResult 


OSErr 


The result code of the function. 




ioNamePtr 


StringPtr 


A pointer to a file or directory name. 




ioVRefNum 


Integer 


A volume specification. 


-> 


ioForeignPr ivBuf f er 


Ptr 


A pointer to the privilege 






information buffer. 




ioForeignPrivReqCount 


Longint 


The size allocated for the buffer. 


— > 


ioForeignPrivActCount 


Longint 


The amount used in buffer. 




ioForeignPrivDirlD 


Integer 


The parent directory ID. 




ioForeignPrivInf ol 


Longint 


Information specific to 






privilege model. 


-> 


ioForeignPrivInf o2 


Longint 


Information specific to 
privilege model. 




ioForeignPrivInf o3 


Longint 


Information specific to 






privilege model. 




ioForeignPrivInf o4 


Longint 


Information specific to 






privilege model. 



DESCRIPTION 

The PBSetForeignPrivs function modifies access information for a file or directory 
on a volume managed by a file system that uses a privilege model different from the 
AFP model 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for PBSetForeignPrivs are 
Trap macro Selector 

_HFSDispatch $0061 



RESULT CODES 

noErr 0 No error 

nsvErr -35 Volume not found 

paramErr -50 Volume is HFS or MPS (that is, it has no foreign 

privilege model), or foreign volume does not 
support these calls 
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Utility Routines 



The File Manager provides several utility routines that allow you to obtain information 
about File Manager queues and file control blocks. These routines insulate your 
application from the need to know about the data structures maintained internally by 
the File Manager. Most applications do not need to use these routines. 



Obtaining Queue Headers 



You can use the hmctions GetFSQHdr, GetVCBQHdr, and GetDrvQHdr to obtain a 
pointer to \he header of the file I/O queue, tiie VCB queue, and the drive queue, 
respectively See the chapter "Queue Utilities" in Inside Macintosh: Operating System 
Utilities for a description of queues and the format of a queue header. 



GetFSQHdr 



You can use the GetFSQHdr function to get a pointer to the header of the file I/O queue. 
FUNCTION GetFSQHdr: QHdrPtr; 

DESCRIPTION 

The GetFSQHdr function returns a pointer to the header of the file I/O queue. 

ASSEMBLY-LANGUAGE INFORMATION 

The global variable FSQHdr contains the header of the file I/O queue. 



GetVCBQHdr 



You can use the GetVCBQHdr function to get a pointer to the header of the VCB queue. 
FUNCTION GetVCBQHdr: QHdrPtr; 

DESCRIPTION 

The GetVCBQHdr function returr\s a pointer to the header of the VCB queue. 

ASSEMBLY-LANGUAGE INFORMATION 

The global variable VCBQHdr contains the header of the VCB queue. The default 
volume's VCB is pointed to by the global variable DefVCBPtr. 
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GetPrvQHdr ~ 

You can use the GetDrvQHdr function to get a pointer to the header of the drive queue. 
FUNCTION GetDrvQHdr: QHdrPtr; 

DESCRIPTION 

The GetDrvQHdr function returns a pointer to the header of the drive queue. 

ASSEMBLY-LANGUAGE INFORMATION 

The global variable DrvQHdr contains the header of the drive queue. 

Adding a Drive 

The AddDr ive procedure allows you to add a drive. 



AddDrive 



You can use the AddDrive procedure to add a drive to the system. 

PROCEDURE AddDrive (drvrRefNum: Integer; drvNum: Integer; 

qEl: DrvQElPtr) ; 

drvrRef Nura A driver reference number. 

drvNum A drive number. 

qEl A pointer to a drive queue element 

DESCRIPTION 

The AddDrive procedure adds a disk drive having the specified driver reference 
number and drive nvimber to the system. The File Manager expands the drive queue 
by adding a copy of the queue element pointed to by the qEl parameter to the end 
of the existing queue. 

Obtaining File Control Block Information 

You can get information from the file control block (FCB) allocated for an open file by 
calling the function PBGetFCBInf o. 
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PBGetFCBInfo 



You can use PBGetFCBInfo to get information about an open file. 

FUNCTION PBGetFCBInfo (paramBlock: FCBPBPtr; async : Boolean): 

OSErr ; 

paramBlock A pointer to a file control block parameter block. 

async A Boolean value that specifies asynchronous (TRUE) or synchronous 

(FALSE) execution. 



Parameter block 



-> 


ioCompletion 


ProcPtr 


A pointer to a completion routine. 


<- 


ioResult 


OSErr 


The result code of the function. 




ioNamePtr 


StringPtr 


A pointer to a pathname. 


-> 


ioVRefNum 


Integer 


A volume specification. 




ioRefNum 


Integer 


The file reference number. 


— > 


ioFCBIndx 


Integer 


An index. 




ioFCBFlNm 


Long In t 


The file ID. 


<— 


ioFCBFlags 


Integer 


File status flags. 


<r- 


ioFCBStBlk 


Integer 


The first allocation block of the file. 


<r- 


ioFCBEOF 


Long In t 


The logical end-of-file. 


<- 


ioFCBPLen 


Longint 


The physical end-of-file. 


<r- 


ioFCBCrPs 


Longint 


The position of the file mark. 


<- 


ioFCBVRefNum 


Integer 


The volume reference number. 




ioFCBClpSiz 


Longint 


The file clump size. 


<- 


ioFCBParlD 


Longint 


The parent directory ID. 



DESCRIPTION 

The PBGetFCBInfo function returns information about the specified open file. If the 
value of ioFCBIndx is positive, the File Manager returns information about the file 
whose index in the FCB buffer is ioFCBIndx and that is located on the volxune specified 
by ioVRefNum (which may contain a drive number, volimie reference number, or 
working directory reference number). If the value of ioVRefNum is 0, all open files are 
indexed; otherwise, only open files on the specified volimie are indexed. 

If the value of ioFCBIndx is 0, the File Manager returns information about the file 
whose file reference number is specified by the ioRef Num field. If the value of 
ioFCBIndx is positive, the ioRef Num field is ignored on input and contains the file 
reference number on output. 

If PBGetFCBInfo executes successfully, the ioNamePtr field contains the name of the 
specified open file. You should pass a pointer to a Str3 1 value if you want that name 
returned. If you pass NIL in the ioNamePtr field, no filename is retvuned. 

The ioFCBFlags field returns status information about the specified open file. See 
"File Control Block Parameter Blocks" beginning on page 2-107 for a description of 
the meaning of the bits in this field. 
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ASSEMBLY-LANGUAGE INFORMATION 

' The trap macro and routine selector for PBGetFCBInf o are 

Trap macro Selector 

_HFSDispatch $0008 



RESULT CODES 



noErr 
nsvErr 
fnOpnErr 
rfNumErr 



0 No error 

-35 Specified volume doesn't exist 

-38 File not open 

-51 Reference number specifies nonexistent access path 



Application-Defined Routin es 

This section describes the application-defined routines whose addresses you pass to 
some of the File Manager routines. You can define a routine that is called after the 
completion of an asynchronous call. 



Completion Routines 

Most low-level File Manager routines can be executed either synchronously (that 
is, the application can't continue until the routine is completed) or asynchronously 
(that is, the application is free to perform other tasks v^^hile the routine is executing). 
Some routines, however, can only be executed synchronously because they use the 
Memory Manager to allocate and release memory. 

When you execute a routine asynchronously, you can specify a completion routine that 
the File Manager executes after the completion of the call. 



MyCompletionProc 



A File Manager completion routine has the following syntax: 
PROCEDURE MyCompletionProc; 



DESCRIPTION 

When you execute a File Manager routine asjnnchronously (by setting its async 
parameter to TRUE), you can specify a completion routine by passing the routine's 
address in the ioCompletion field of the parameter block passed to the routine. 
Because you requested asynchronous execution, the File Manager places an I/O request 
in the file I/O queue and returns control to your application — possibly even before the 
actual I/O operation is completed. The File Manager takes requests from the queue one 
at a time and processes them; meanwhile, your application is free to do other processing. 
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A routine executed asynchronously returns control to your application with the result 
code noErr as soon as the call is placed in the file I/O queue. This result code does not 
indicate that the call has successfully completed, but simply indicates that the call was 
successfully placed in the queue. To determine when the call is actually completed, you 
can inspect the ioResul t field of the parameter block This field is set to a positive 
nimiber when the call is made and set to the actual result code when the call is 
completed. If you specify a completion routine, it is executed after the result code is 
placed in ioResult. 



ASSEMBLY-LANGUAGE INFORMATION 

When your completion routine is called, register AO contains a pointer to the parameter 
block of the asynchronous call, and register DO contains the result code. The value in 
register DO is always identical to the value in the ioResult field of the parameter block. 
A completion routine must preserve all registers other than AO, Al, and D0-D2. 



SPECIAL CONSIDERATIONS 

Because a completion routine is executed at interrupt time, it should not allocate, move, 
or purge memory (either directly or indirectiy) and should not depend on the validity of 
handles to unlocked blocks. 

If your completion routine uses application global variables, it must also enstue that 
register A5 contains the address of the boundary between your application global 
variables and your application parameters. For details, see the discussion of the 
hmctions SetCurrent A5 and SetAS in the chapter "Memory Management Utilities" 
in Inside Macintosh: Memory, 



SEE ALSO 



For a more complete discussion of interrupt-level processing and its limitations, see the 
chapter "Introduction to Processes and Tasks" in Inside Macintosh: Processes, 
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Suminary of the FUe Manager 



Pascal Summary 



Constants 



CONST 

{Gestalt constants} 

gestaltFSAttr = • f s {file system attributes selector} 

gestaltFullExtFSDispatching= 0; {exports HFSDispatch traps} 

gestaltHasFSSpecCalls = 1; {supports FSSpec records} 

(directory IDs} 



f sRtParlD 


= 1; 


(directory ID of root directory's parent} 


f sRtDirlD 


= 2; 


(directory ID of volume's root directory} 


{access modes for 


opening files} 


f sCurPerm 


= 0; 


(whatever permission is allowed} 


f sRdPerm 


= 1; 


(read permission} 


f sWrPerm 


= 2; 


(write permission} 


f sRdWrPerm 


= 3; 


(exclusive read/write permission} 


f sRdWrShPerm 


= 4; 


(shared read/write permission} 


{file mark positioning modes} 




fsAtMark 


= 0; 


(at current mark} 


fsFromStart 


= 1; 


(set mark relative to beginning of file} 


f sFromLEOF 


= 2; 


(set mark relative to logical end-of-file} 


fsFromMark 


= 3; 


(set mark relative to current mark} 


rdVerify 


= 64; 


(add to above for read- verify} 


(values for ioSearchBits in PBCatSearch parameter block} 


fsSBPartialName 


= 1; 


(substring of name} 


fsSBFullName 


= 2; 


(full name} 


fsSBFlAttrib 


= 4; 


(directory flag; software lock flag} 


fsSBNegate 


= 16384; 


(reverse match status} 


(for files only} 






fsSBFlFndrlnfo 


= 8; 


(Finder file info} 


fsSBFlLgLen 


= 32; 


(logical length of data fork} 


fsSBFlPyLen 


= 64; 


(physical length of data fork} 
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f sSBFlRLgLen 




f sSBFlRPyLen 


— ZOO ; 


f sSBFlCrDat 


— tzi 1 

Dl2 ; 


f sSBFlMdDat 


— 1 no /* 


f sSBFlBkDat 


— o c\A a 


f sSBFlXFndr Tn f n 


— /I noc 

- ^uyb 


f sSBFlParlD 


— Q 1 Q O 


{for directories 


only } 


fsSBDrUsrWds 


= 8? 


fsSBDrNmFls 


= 16; 


fsSBDrCrDat 


= 512; 


fsSBDirMdDat 


= 1024 


fsSBDrBkDat 


= 2048 


fsSBDrFndrlnfo 


= 4096 


fsSBDrParlD 


= 8192 



{logical length of resource fork} 

{physical length of resource fork} 

{file creation date} 

{file modification date} 

{file backup date} 

{more Finder file info) 

{file's parent ID} 

{Finder directory info} 
{number of files in directory} 
{directory creation date} 
{directory modification date} 
{directory backup date} 
{more Finder directory info} 
{directory's parent ID} 




Z3 

Hi 

(Q 
CD 



{value of vMForeignPrivID in file attributes buffer) 
fsynixPriv = 1; {A/UX privilege model} 

{bit positions in vMAttrib field of GetVolParmsInf oBuf f er } 
bHasBlankAccessPrivileges 



bHasBTreeMgr 
bHasFilelDs 
bHasCatSearch 
bHa sU s e r Gr oupL i s t 
bHasPersonalAccessPrivileges 

= 9; 

bHasFolderLock = lo 

bHasShortName = ii 

bHasDesktopMgr = 12 

bHasMoveRename = 13 

bHasCopyFile = 14 

bHasOpenDeny = 15 

bHasExtFSVol = 16 

bNoSysDir = 17 

bAccessCntl = is 

bNoBootBlks = 19 

bNoDe skit ems = 20 

bNoSwitchTo = 25 

bTrshOffLine = 26 

bNoLclSync = 27 

bNoVNEdit = 28 



{volume supports inherited privileges} 
{reserved} 

{volume supports file ID functions) 
{volume supports PBCatSearch) 
{volume supports AFP privileges) 

{local file sharing is enabled) 
{volume supports locking of folders) 
{volume supports AFP short names) 
{volume supports Desktop Manager) 
{volume supports _MoveRename} 
{volume supports _CopyFile) 
{volume supports shared access modes) 
{volume is external file system volume) 
{volume has no system directory) 
{volume supports AFP access control) 
{volume is not a startup volume) 
{do not place objects on the desktop) 
{do not switch launch to applications) 
{zoom volume when it is unmounted) 
{don't let Finder change mod. date) 
{lock volume name) 



Summary of the File Manager 



2-241 



TIVO-408691 



CHAPTER 2 



File Manager 



bNQMiniFndr 
bLdcalWList 
bLimitFCBs 



29 
30 
31 



{reserved; always 1} 

{use shared volume handle for window list} 
{limit file control blocks) 



{media type in remote mounting information) 
AppleShareMediaType 

= 'afpm*; {an AppleShare volume) 

{user authentication methods in AFP remote mounting information) 



JcNoUserAuthentication = 1 

kPassword = 2 

kEncryptPassword = 3 

kTwoWayEncryptPassword = 6 



{guest status; no password needed) 

{8-byte password) 

{encrypted 8-byte password) 

{two-way random encryption; ) 

{ authenticate both user and server) 



Data Types 



File System Specification Record 



TYPE 

FSSpec 

RECORD 

vRefNum: 
parlD: 
name : 

END; 



{file system specification) 

Integer; {volume reference number) 
Longint; {directory ID of parent directory) 
Str63; {filename or directory name) 



FSSpecPtr 
FSSpecHandle 

FSSpecArray = 
FSSpecArrayPtr 
FSSpec Array Handle = 



'"FSSpec; 
^FSSpecPtr; 

ARRAY [0..0] OF FSSpec; 

"FSSpecArray; 

" FSSpecArray Pt r ; 



File and Directory Parameter Blocks 

TYPE 

ParamBlkType = (ioParam, fileParam, voliameParam, cntrlParam, 

slotDevParam, multiDevParam, accessParam, 
objParam, copyParam, wdParam, fidParam, csParam, 
f oreignPrivsParam) ; 
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ParmBlkPtr 

ParamBlockRec 

RECORD 

qLink: 

qType: 

ioTrap : 

ioCmdAddr : 

ioCompletion: 

ioResult : 

ioNamePtr : 

ioVRefNum: 
CASE ParamBlkType OF 
ioParam: 

(ioRefNum: 

ioVersNum: 

ioPermssn : 

ioMisc: 

ioBuf fer : 

ioReqCount : 

ioActCount: 

ioPosMode : 

ioPosOf f set : 
f ileParam: 



'ParamBlockRec; 



volumeParam: 
(filler2: 
ioVolIndex: 
ioVCrDate: 



QElemPtr; 
Integer; 
Integer; 
Ptr; 

ProcPtr; 
OSErr; 
StringPtr; 
Integer; 



Integer; 

SignedByte; 

SignedByte; 

Ptr; 

Ptr; 

Long In t; 
Long In t; 
Integer; 
Longint) ; 



{basic File Manager parameter block} 

{next queue entry} 

(queue type} 

(routine trap} 

(routine address} 

(pointer to completion routine} 

(result code} 

(pointer to pathname} 

(volume specification} 



(file reference number} 
(version number} 
(read/write permission} 
(miscellaneous} 
(data buffer} 

(requested number of bytes} 
(actual number of bytes} 
(positioning mode and newline char.} 
{positioning offset} 



(ioFRefNum: 


Integer; 


(file reference number} 


ioFVersNum: 


SignedByte; 


(file version number (unused)} 


fillerl: 


SignedByte; 


(reserved} 


ioFDirlndex: 


Integer 




(directory index} 


ioFlAttrib: 


SignedByte; 


(file attributes} 


ioFlVersNum: 


SignedByte; 


(file version number (unused)} 


ioFlFndrlnfo: 


FInfo; 




{information used by the Finder} 


ioFlNum: 


Lorigint, 




{file ID} 


ioFlStBlk: 


Integer, 




(first alloc, blk. of data fork} 


ioFlLgLen: 


Longint, 




(logical EOF of data fork} 


ioFlPyLen: 


LongInt, 




(physical EOF of data fork} 


ioFlRStBlk: 


Integer, 




(first, alloc, blk. of resource fork} 


ioFlRLgLen: 


Longint, 




(logical EOF of resource fork} 


ioFlRPyLen: 


LongInt, 




(physical EOF of resource fork} 


ioFlCrDat : 


Longint , 




(date and time of creation} 


ioFlMdDat : 


Longint; 




(date and time of last modification} 



Longint 
Integer 
Longint 



{reserved} 
(volume index} 

(date and time of initialization} 
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-UoVLsBkUp: 
'ioVAtrb: 
ioVNmFlS: 
ioVDirSt: 
ioVBlLn: 
ioVNitiAlBlks: 
ioVAlBlkSiz: 
ioVClpSiz: 
ioAlBlSt: 
ioVNxtFNiun: 
ioVFrBlk: 
END; 

HParmBlkPtr 
HParamBlockRec 
RECORD 
qLink : 
qType: 
ioTrap: 
ioCmdAddr: 
ioCompletion: 
ioResult : 
ioNamePtr : 
ioVRefNum: 
CASE ParamBlkType 
ioParam: 
(ioRefNum: 
ioVersNum: 
ioPermssn: 
ioMisc: 
ioBuf fer : 
ioReqCount : 
ioActCount : 
ioPosMode : 
ioPosOffset: 
f ileParam: 
(ioFRefNum: 
ioFVersNum: 
fillerl; 
ioFDirlndex: 
ioFlAttrib: 
ioFlVersNum: 
ioFlFndrlnfo: 
ioDirlD: 



Long In t ; 
Integers- 
Integer; 
Integer; 
Integer; 
Integer; 
Long In t ; 
Long In t ; 

Integer; 

Longint ; 

Integer) ; 



{date and time of last modification) 

(volume attributes) 

{number of files in root directory} 

{first block of directory} 

{length of directory in blocks} 

{number of allocation blocks} 

{size of allocation blocks) 

{default clump size} 

{first bloclc in block map} 

{next unused file ID) 

{number of unused allocation blocks) 



'^HParamBlockRec ; 



QElemPtr; 
Integer; 
Integer; 
Ptr; 

ProcPtr ; 
OSErr; 
StringPtr; 
Integer; 



OF 



Integer; 

SignedByte; 

SignedByte; 

Ptr; 

Ptr; 

Longint ; 
Longint ; 
Integer; 
Longint) ; 

Integer; 

SignedByte; 

SignedByte; 

Integer; 

SignedByte; 

SignedByte; 

FInfo; 

Longint ; 



(HFS parameter block} 

{next queue entry} 

{queue type) 

{routine trap) 

{routine address) 

{pointer to completion routine) 

{result code) 

(pointer to pathname} 

(volume specification) 



(file reference number} 
(version number) 
(read/write permission} 
(miscellaneous } 
(data buffer) 

(requested number of bytes} 
{actual number of bytes} 
{positioning mode and newline char.} 
(positioning offset) 

(file reference number} 

(file version number (unused)} 

(reserved) 

(directory index) 

{file attributes} 

(file version number (unused)} 

(information used by the Finder} 

(directory ID or file ID} 
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ioFlStBlk 
ioFlLgLen 
ioFlPyLen 
ioFlRStBlk 
ioFlRLgLen 
ioFlRPyLen 
ioFlCrDat : 
ioFlMdDat : 
volumeParam: 
(filler2: 
ioVol Index: 
ioVCrDate : 
ioVLsMod: 
ioVAtrb: 
ioVNmFls: 
ioVBitMap: 
ioAllocPtr : 
ioVNmAlBlks 
ioVAlBlkSiz 
ioVClpSiz: 
ioAlBlSt: 
ioVNxtCNID: 
ioVFrBlk: 
ioVSigWord 
ioVDrvInfo 
ioVDRefNum 
ioVFSID: 
ioVBkUp: 
ioVSeqNum: 
ioVWrCnt : 
ioVFilCnt: 
ioVDirCnt : 
ioVFndrlnfo 



accessParam: 
(filler3: 
ioDeny Modes : 
filler4: 
fillers: 
ioACUser : 
fillerG: 
ioACOwnerlD: 
ioACGroupID: 
ioACAccess : 



Integer; {first alloc, blk. of data fork) 

Lorigint; {logical EOF of data fork) 

Longlnt; {physical EOF of data fork) 

Integer; {first alloc, blk. of resource fork) 

Longlnt; {logical EOF of resource fork) 

Longlnt; {physical EOF of resource fork) 

Longlnt; {date and time of creation) 

Longlnt); {date and time of last modification) 

Longlnt; {reserved) 

Integer; {volume index) 

Longlnt; {date and time of initialization) 

Longlnt; {date and time of last modification) 

Integer; {volume attributes) 

Integer; {number of files in root directory) 

Integer; {first block of volume bitmap) 

Integer; {first block of next new file) 

Integer; {number of allocation blocks) 

Longlnt; {size of allocation blocks) 

Longlnt; {default clump size) 

Integer; {first block in volume map) 

Longlnt; {next unused node ID) 

Integer; {number of unused allocation blocks) 

Integer; {volume signature) 

Integer; {drive number) 

Integer; {driver reference number) 

Integer; {file-system identifier) 

Longlnt; {date and time of last backup) 

Integer; {used internally) 

Longlnt; {volume write count) 

Longlnt; {number of files on volume) 

Longlnt; {number of directories on volume) 

ARRAY[1..8] OF Longlnt); 

{information used by the Finder) 

Integer; {reserved) 

Integer; {access mode information) 

Integer; {reserved) 

SignedByte; {reserved) 

SignedByte; {user access rights) 

Longlnt; {reserved) 

Longlnt; {owner ID) 

Longlnt; {group ID} 

Longlnt); {directory access rights) 



CQ 
CD 
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obiParam : 
.,Cfiller7: 

ioObjType: 

ibobjNamePtr : 

ioObjID: 
copy Pa ram: 

(ioDstVRefNujn: 

fillers: 

ioNewName: 

ioCopyName: 

ioNewDirlD: 
wdParam : 

(filler9: 

ioWDIndex: 

ioWDProcID: 

ioWDVRefNum: 
fillerlO: 
fillerll: 
fillerl2: 
f illerl3: 
ioWDDirlD: 
f idParam: 

(fillerl4: 
ioDestNamePtr : 
fillerlB: 
ioDestDirlD: 
fillerl6: 
fillerl?: 
ioSrcDirlD: 
fillerlS: 
ioFilelD: 
csParam: 

(ioMatchPtr: 
ioReqMatchCount : 
ioActMatchCount : 
loSearchBits: 
ioSearchInf ol : 
ioSearchInf o2 : 
ioSearchTime: 
ioCatPosition: 
ioOptBuf f er: 
ioOptBufSize: 



Integer; {reserved) 

Integer; {function code} 

Ptr; {ptr to returned creator /group name} 

Longint) ; {creator /group ID} 

Integer; {destination volume identifier} 

Integer; {reserved} 

Ptr; {pointer to destination pathname} 

Ptr; {pointer to optional name} 

Longint) ; {destination directory ID} 

Integer; {reserved} 

Integer; {worJcing directory index} 

Longint; {working directory user identifier} 

Integer; {working directoory ' s vol. ref. num.} 

Integer; {reserved} 

Longint; {reserved} 

Longint; {reserved} 

Longint; {reserved} 

Longint); {working directory's directory ID} 

Longint ; { reserved } 

StringPtr; {pointer to destination filename} 

Longint; {reserved} 

Longint; {destination parent directory ID) 

Longint; {reserved} 

Longint; {reserved} 

Longint; {source parent directory ID} 

Integer; {reserved} 

Longint) ; {file ID} 



FSSpecArrayPt r ; 
Longint ; 
Longint; 
Longint ; 
CInfoPBPtr; 
CInfoPBPtr; 
Longint ; 
CatPositionRec; 
Ptr; 

Longint) ; 



{pointer to array of matches} 
{max. number of matches to return} 
{actual number of matches} 
{enable bits for matching rules} 
{pointer to values and lower bounds} 
{pointer to masks and upper bounds} 
{maximum time to search} 
{current catalog position} 
{pointer to optional read buffer} 
{length of optional read buffer} 
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f oreignPr ivParam : 
(filler21: 
filler22: 

ioForeignPrivBuf f er : 
ioForeignPrivReqCount : 
ioForeignPrivActCount : 
filler23: 

ioForeignPrivDirlD: 



ioForeignPrivIrifol 
ioForeignPrivInfo2 
ioForeignPrivInfo3 
ioForeignPrivInfo4 
END; 



Longint; {reserved) 

Longint; {reserved} 

Ptr; {privileges data buffer} 

Longint; {size of buffer) 

Longint; (amount of buffer used) 

Longint; (reserved) 

Longint; (parent directory ID of } . 

{. foreign file or directory) 

Longint; {privileges data) 

Longint; (privileges data) 

Longint; (privileges data) 

Longint) ; (privileges data) 



I 



2J 

fU 
(Q 
<D 



Catalog Information Parameter Blocks 



TYPE 

Cinf oType 



(hf ilelnfo, dirlnfo) ; 



CInfoPBPtr 
CInfoPBRec 
RECORD 



'^CInfoPBRec; 
(catalog information parameter block} 



qLink: 


QElemPtr; 


(next queue entry) 


qType: 


Integer; 


(queue type) 


ioTrap : 


Integer; 


(routine trap) 


ioCmdAddr : 


Ptr; 


(routine address) 


ioCompletion : 


ProcPtr; 


(pointer to completion routine} 


ioResult : 


OSErr; 


(result code) 


ioNamePtr : 


StringPtr; 


(pointer to pathneime} 


ioVRefNum: 


Integer; 


(volume specification) 


ioFRefNum: 


Integer; 


(file reference number) 


ioFVersNum: 


SignedByte; 


(version number) 


fillerl: 


SignedByte; 


{reserved} 


ioFDirlndex: 


Integer; 


(directory index) 


ioFlAttrib: 


SignedByte; 


(file or directory attributes) 


ioACUser : 


SignedByte; 


(directory access rights} 



CASE CInfoType OF 
hFilelnfo: 

(ioFlFndrlnfo: 

ioDirlD: 

ioFlStBlk: 

ioFlLgLen: 

ioFlPyLen: 



FInfo; (information used by the Finder) 

Longint; (directory ID or file ID) 

Integer; (first alloc, blk. of data fork) 

Longint; (logical EOF of data fork) 

Longint; (physical EOF of data fork) 
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..^ ioFlRStBlk; 


Integer; 


' ioFlRLgLen: 


Longlnt; 


ioFlRPyLen: 


Longlnt; 


ioFlCrbat : 


Longint; 


ioPlMdDat : 


Longint; 


ioFlBkDat : 


Longint; 


ioFlXFndrlnfo: 


FXInfo; 


ioFlParlD: 


Longlrit; 


ioFlClpSiz: 


Longint) ; 


dirlnfo: 




(ioDrUsrWds: 


Dinfo; 


ioDrDirlD: 


Longint ; 


ioDrNmFls : 


Integer; 


fillers : 


ARRAYtl. . 


ioDrCrDat : 


Longint ; 


ioDrMdDat : 


Longint; 


ioDrBkDat : 


Longint; 


ioDrFndrlnfo: 


DXInfo; 


ioDrParlD: 


Longint) ; 



END; 



{first alloc, blk. of resource fork} 
{logical EOF of resource fork} 
{physical EOF of resource fork} 
{date and time of creation} 
{date and time of last modification} 
{date and time of last backup} 
{additional Finder information} 
(file parent directory ID} 
(file's clump size} 

{information used by the Finder} 
(directory ID} 

{number of files in directory} 
Integer; 

(date and time of creation} 
{date and time of last modification} 
{date and time of last backup} 
{additional Finder information} 
{directory's parent directory ID} 



Catalog Position Record 

TYPE 

CatPositionRec 
RECORD 

initialize: 
priv: 
END; 



(catalog position record} 



Longint ; 

ARRAY[1..6] OF Integer; 



(starting point} 
{private data} 



Catalog Move Parameter Block 



TYPE 

CMovePBPtr . 

CMovePBRec 

RECORD 
qLink: 
qType: 
ioTrap : 
ioCmdAddr : 
ioCompletion: 
ioResult : 
ioNamePtr : 
ioVRefNum: 



= "^CMovePBRec; 



QElemPtr; 
Integer; 
Integer; 
Ptr; 

ProcPtr; 
OSErr; 
StringPtr ; 
Integer; 



(catalog move parameter block} 

(next queue entry} 

{queue type} 

(routine trap} 

(routine address} 

(pointer to completion routine} 

(result code} 

(pointer to pathname} 

(volume specification} 
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fillerl: 
ioNewName : 
filler2: 
ioNewDirlD: 
filler3: 
ioDirlD: 
END; 



Longint; (reserved) 

StringPtr; {name of new directory) 

Longint; {reserved} 

Longint; {directory ID of new directory) 

ARRAY [1,. 2] OF Longint; (reserved) 



Longint ; 



(directory ID of current directory) 



Working Directory Parameter Block 



TYPE 

WDPBPtr 
WDPBRec 
RECORD 



"WDPBRec; 



(working directory parameter block) 



qLink: 


QElemPtr; 


(next queue entry) 


qType: 


Integer; 


(queue type) 


ioTrap: 


Integer; 


(routine trap) 


i oCmdAddr : 


Ptr; 


{routine address) 


ioCompletion : 


ProcPtr; 


(pointer to completion routine} 


ioResult : 


OSErr ; 


(result code) 


ioNamePtr : 


StringPtr; 


(pointer to patliname} 


ioVRefNum: 


Integer; 


(volume specification) 


fillerl: 


Integer; 


(reserved) 


ioWDIndex: 


Integer; 


(working directory index) 


ioWDProcID: 


LohgInt ; 


(working directory user identifier} 


ioWDVRefNum: 


Integer; 


(working directory's vol. ref. num.} 


f iller2: 


ARRAY[1. .7] 


OF Integer; (reserved} 


ioWDDirlD: 


Longint ; 


(working directot^y ' s (^ijcectory ID}' 



END; 



File Control Block Parameter Block 



TYPE 

FCBPBPtr 

FCBPBRec 

RECORD 
qLink: 
qType: 
ioTrap: 
ioCmdAddr : 
ioCompletion : 
ioResult : 
ioNamePtr : 
ioVRefNum: 



"FCBPBRec; 



QElemPtr; 
Integer; 
Integer; 
Ptr; 

ProcPtr; 
OSErr; 
StringPtr; 
Integer; 



(file control block parameter block} 

(next queue entry} 

(queue type} 

(routine trap} 

(routine address} 

(pointer to completion routine) 

(result code) 

(pointer to pathname} 

(volume specification} 
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ioRefNum: 


Integer; 


{file reference number} 


'filler: 


Integer; 


{reserved} 


ioFCBIndx: 


Integer, 


{FCB index} 


fillerl: 


Integer, 


{reserved} 


ioFCBFlNm: 


LongInt 


(file ID} 


ioPCBFlags: 


Integer J 


{flags} 


ioFCBStBlk: 


Integer 


{first allocation block of file} 


ioFCBEOF: 


LongInt 


{logical end-of-file} 


ioFCBPLen: 


LongInt 


f (physical end-of-file} 


ioFCBCrPs: 


LongInt 


; {position of the file mark} 


ioFCBVRefNum: 


Integer 


; {volume reference number} 


ioFCBClpSiz: 


LongInt 


; {file's clump size} 


ioFCBParlD: 


LongInt 


{parent directory ID} 



END; 



Volume Attributes Buffer 



TYPE 

GetVolParmsInfoBuf fer = 
RECORD 

vMVer s ion : In t eger ; 

vMAttrib: LongInt; 

vMLoca IHand : Handl e ; 

vMServerAdr : LongInt ; 

vMVolumeGrade : LongInt ; 

vMForeignPrivID: Integer; 
END; 



{version number} 
{volume attributes} 
{reserved} 

{network server address} 
{relative speed rating} 
{foreign privilege model} 



Volume Mounting Information Records 



TYPE 

VolumeType 
VolMountlnfoPtr 
VolMountlnfoHeader 
RECORD 

length: 

media: 
END; 



= OSType; 

= ''VolMountlnfoHeader; 

{volume mounting information} 

Integer; {length of mounting information} 

VolumeType; {type of volume} 



AFPVolMountlnfoPtr 

AFPVolMountlnfo 

RECORD 

length: 

media: 



= ""APPVolMountlnfo; 

{AFP volume mounting information} 

Integer; {length of mounting information} 

VolumeType; {type of volume} 
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flags : 

nbplnterval : 
nbpCount : 
uamType ; 
zoneNameOf f set : 
s erverNameO f f s e t 
volNameOf f set : 
userNameOf f set : 
userPasswordOf fset 

volPasswordOf f set : 



AFPData : 



Integer; 
SignedByte; 
SignedByte; 
Integer; 
Integer; 
Integer; 
Integer; 
Integer ; 

Integer; 

Integer; 
PACKED ARRAY[1. 



{reserved; must be set to 0} 
{NfiP retry interval} 
{NBP retry count} 
{user authentication method} 
{offset to. zone name} 
{offset server name} 
{offset to volume name} 
{offset to user name} 

{offset to user password} 

{offset to volume -password} 
. .144) OF CHAR; 
{standard AFP mounting info} 



END; 



Internal Data Types 



Volume and File Control Blocks 

TYPE 

= {volume control bloc)c} 

RECORD 



qLink: 


QElemPtr; 


{next queue entry} 


qType: 


Integer; 


{queue type} 


vcbFlags: 


Integer; 


{volume flags (bit 15 = 1 if dirty)} 


vcbSigWord: 


Integer; 


{volume signature} 


vcbCrDate: 


LongInt ; 


{date and time of volume creation} 


vcbLsMod : 


LongInt ; 


{date and time of last modification} 


vcbAtrb: 


Integer; 


{volume attributes} 


vcbNmFls : 


Integer; 


{number of files in root directory} 


vcbVBMSt : 


Integer; 


{first block of volume bitmap} 


vcbAllocPtr : 


Integer; 


{start of next allocation search} 


vcbNmAlBlks: 


Integer; 


{number of allocation blocks in volume} 


vcbAlBlkSiz : 


LongInt ; 


{size (in bytes) of allocation blocks} 


vcbClpSiz: 


LongInt; 


{default clump size} 


vcbAlBlSt: 


Integer; 


{first allocation block in volume} 


vcbNxtCNID: 


LongInt ; 


{next unused catalog node ID} 


vcbFreeBks : 


Integer; 


{number of unused allocation blocks} 


vcbVN: 


String [27}; 


{volume name} 


vcbDrvNum : 


Integer; 


{drive number} 


vcbDRefNum: 


Integer; 


{driver reference number} 


vcbFSID: 


Integer; 


{file-system identifier} 
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:ycbVRefNum: 
vcbMAdr : 
vcbBufAdr: 
vcbMLen : 
vcbDir Index: 
vcbDirBlk: 
vcbVolBkUp: 
vcbVSeqNum: 
vcbWrCnt : 
vcbXTClpSiz: 
vcbCTClpSiz : 
vcbNmRtDirs : 
vcbFilCnt : 
vcbDirCnt : 
vcbFndrlnfo: 

vcbVCSize: 
vcbVBMCSiz: 
vcbCtlCSiz: 
vcbXTAlBlks : 
vcbCTAlBlks : 
vcbXTRef : 
vcbCTRef : 
vcbCtlBuf : 
vcbDirlDM: 
vcbOf f SM: 
END; 



Integer; {volume reference nximber) 

Ptr; {used internally} 

Ptr; {used internally) 

Integer; {used internally) 

Integer; {used internally) 

Integer; {used internally) 

Longint; {date and time of last backup) 

Integer; {volume backup sequence number) 

Longint; {volume write count) 

Longint; {clump size for extents overflow file) 

Longint; {clump size for catalog file) 

Integer; {number of directories in root dir.) 

Longint; {number of files in volume) 

Longint; {number of directories in volume) 

ARRAY [1.. 8] OF Longint; 

{information used by the Finder) 

Integer; {used internally) 

Integer; {used internally) 

Integer; {used internally) 

Integer; {size of extents overflow file) 

Integer; {size of catalog file) 

Integer; {ref. num. for extents overflow file) 

Integer; {ref, num. for catalog file) 

Ptr; {ptr. to extents and catalog caches) 

Longint; {directory last searched) 

Integer; {offspring index at last search) 



FCB 

RECORD 



{file control block) 



fcbFlNum: 


Longint; 


{file ID) 


f cbFlags : 


Integer; 


{file flags) 


fcbSBlk: 


Integer; 


{first allocation block of file) 


fcbEOF: 


Longint ; 


{logical end-of-file) 


fcbPLen: 


Longint ; 


{physical end-of-file) 


f cbCrPs : 


Longint ; 


. {current file mark position) 


fcbVPtr: 


Ptr; 


{pointer to volume control block) 


fcbBfAdr: 


Ptr; 


{pointer to access path buffer) 


f cbFlPos : 


Integer; 


{reserved) 


f cbClmpSize: 


Longint ; 


{file clump size) 


fcbBTCBPtr: 


Ptr; 


{pointer to B*-tree control block) 


f cbExtRec : 


ExtDataRec; 


{first three file extents) 


f cbFType : 


Longint ; 


{filers four Finder type bytes) 
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f cbCatPos: 
fcbDirlD: 
fcbCName: 
END; 



Longint; {catalog hint for use on Close} 
Longint; {file's parent directory ID} 
String[31]; {name of file} 



Drive Queue Elements 

TYPE 

DrvQEl 
RECORD 

qLink: QElemPtr; 
qType: Integer; 
dQDrive: Integer; 
dQRefNum: Integer; 
dQFSID: Integer; 
dQDrvSz: Integer; 
dQDrvS22: Integer; 
END; 



{drive queue element} 

{next queue entry} 

{flag for dQDrvSz and dQDrvS22} 

{drive number} 

{driver reference number} 

{file-system identifier} 

{number of logical blocks on drive} 

{additional field for large drives} 



High-Level File Access Routines 



Reading, Writing, and Closing Files 



FUNCTION FSRead 



FUNCTION FSWrite 



FUNCTION FSClose 



(refNum: Integer; VAR count: Longint; 
buffPtr: Ptr) : OSErr; 

(refNum: Integer; VAR count: Longint; 
buffPtr: Ptr): OSErr; 

(refNum: Integer) : OSErr; 



Manipulating the File Mark 

FUNCTION GetFPos 
FUNCTION SetFPos 



(refNum: Integer; VAR filePos: Longint) 

(refNum: Integer; posMode: Integer; 
posOff: Longint): OSErr; 



OSErr; 



Manipulating the End-of-File 

FUNCTION Get EOF 
FUNCTION SetEOF 

Allocating File Blocks 

FUNCTION Allocate 
FUNCTION AllocContig 



(refNum: Integer; VAR logEOF: Longint) : OSErr; 
(refNum: Integer; logEOF: Longint): OSErr; 



(refNum: Integer; VAR count: Longint): OSErr; 
(refNum: Integer; VAR count: Longint): OSErr; 
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Low-Level File Access Routines 



Reading, Writing, and Closing 

FUNCTION PBRead 
FUNCTION PBReadSync 
FUNCTION PBReadAsync 
FUNCTION PBWrite 
FUNCTION PBWriteSync 
FUNCTION PBVJriteAsync 
FUNCTION PBClose 
FUNCTION PBCloseSync 
FUNCTION PBCloseAsync 

Manipulating the File Mark 

FUNCTION PBGetFPos 
FUNCTION PBGetFPosSync 
FUNCTION PBGetFPosAsync 
FUNCTION PBSetFPos 
FUNCTION PBSetFPosSync 
FUNCTION PBSetFPosAsync 

Manipulating the End-o£-File 

FUNCTION PBGetEOF 
FUNCTION PBGetEOFSync 
FUNCTION PBGetEOFAsync 
FUNCTION PBSetEOF 
FUNCTION PBSetEOFSync 
FUNCTION PBSetEOFAsync 



Files 

(paramBlock: 
( par cunB lock: 
(paramBlock: 
(paramBlock r 
(paramBlock: 
(paramBlock: 
(paramBlock: 
(paramBlock : 
(paramBlock: 



ParmBlkPtr; async: Boolean): OSErr; 

ParmBlkPtr) : OSErr; 

ParmBlkPtr) : OSErr; 

ParmBlkPtr; async: Boolean): OSErr; 

ParmBlkPtr) : OSErr; 

ParmBlkPtr) : OSErr; 

ParmBlkPtr; async: Boolean): OSErr; 

ParmBlkPtr) : OSErr; 

ParmBlkPtr) : OSErr; 



(paramBlock: ParmBlkPtr; async: Boolean): OSErr; 

(paramBlock: ParmBlkPtr): OSErr; 

(paramBlock: ParmBlkPtr): OSErr; 

(paramBlock: ParmBlkPtr; async: Boolean): OSErr; 

(paramBlock: ParmBlkPtr): OSErr; 

(paramBlock: ParmBlkPtr): OSErr; 

(paramBlock: ParmBlkPtr; async: Boolean): OSErr; 

(paramBlock: ParmBlkPtr): OSErr; 

(paramBlock: ParmBlkPtr) : OSErr; 

(paramBlock: ParmBlkPtr; async: Boolean) : OSErr; 

(paramBlock: ParmBlkPtr): OSErr; 

(paramBlock: ParmBlkPtr): OSErr; 



Allocating File Blocks 

FUNCTION PBAl locate 
FUNCTION PBAllocateSync 
FUNCTION PBAllocateAsync 
FUNCTION PBAllocContig 
FUNCTION PBAllocContigSync 



(paramBlock: ParmBlkPtr; async: Boolean): OSErr; 

(paramBlock: ParmBlkPtr) : OSErr; 

(paramBlock: ParmBlkPtr): OSErr; 

(paramBlock: ParmBlkPtr; async: Boolean): OSErr; 

(paramBlock: ParmBlkPtr): OSErr; 



FUNCTION PBAllocContig Async (paramBlock: ParmBlkPtr): OSErr; 
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Updating Files 

FUNCTION PBFlushFile 
FUNCTION PBFlushFileSync 
FUNCTION PBFlushFileAsync 



(paramBlock: ParmBlkPtr; async: Boolean): OSErr; 
(paramBlock: ParmBlkPtr) : OSErr; 
(paramBlock: ParmBlkPtr) : OSErr; 



High-level Volume Access Routines 



Unmounting Volumes 

FUNCTION UnmountVol 
FUNCTION Eject 

Updating Volumes 

FUNCTION FlushVol 



(volName: StringPtr; vRefNum: Integer) : OSErr; 
{volName: StringPtr; vRefNum: Integer) : OSErr; 



(volName: StringPtr; vRefNum: Integer) : OSErr; 



I 



3 

a> 
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Manipulating the Default Volume 

FUNCTION GetVol (volName: StringPtr; VAR vRefNum: Integer) : 

OSErr; 

FUNCTION SetVol (volName: StringPtr; vRefNum: Integer): OSErr; 

FUNCTION HGetVol (volName: StringPtr; VAR vRefNum: Integer; 

VAR dirlD: Longint) : OSErr; 

FUNCTION HSetVol (volName: StringPtr; vRefNum: Integer; 

dirlD: Longint) : OSErr; 

Obtaining Volume Information 

FUNCTION GetVInfo (drvNum: Integer; volName: StringPtr; 

VAR vRefNura: Integer; VAR freeBytes: Longint): 
OSErr; 

FUNCTION GetVRefNum (refNum: Integer; VAR vRefNurri: Integer) : OSErr; 

Low-Level Volume Access Routines 



Mounting and Unmounting Volumes 

FUNCTION PBMountVol (paramBlock: ParmBlkPtr): OSErr; 

FUNCTION PBUnmountVol (paramBlock: ParmBlkPtr) : OSErr; 

FUNCTION PBEject (paramBlock: ParmBlkPtr) : OSErr; 

FUNCTION PBOf fLine (paramBlock: ParmBlkPtr) : OSErr; 
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Updating Volumes 

FUNCTION PBFlushVol 
FUNCTI.QN PBFlushVolSync 
FUNCTION PBFlushVolAsync 



(paramBlock: ParmBlkPtr; async: Boolean): OSErr; 
(paramBlock: ParmBlkPtr): OSErr; 
(paramBlock: ParmBlkPtr): OSErr; 



Obtaining 

FUNCTION 

FUNCTION 
FUNCTION 
FUNCTION 

FUNCTION 
FUNCTION 
FUNCTION 

FUNCTION 
FUNCTION 



Volume Information 

PBHGetVInfo 



(paramBlock : 
OSErr; 
(paramBlock: 
(paramBlock : 

(paramBlock: 
OSErr; 
(paramBlock: 
(paramBlock: 

(paramBlock: 
OSErr; 

PBHGetVolParmsSync (paramBlock 
PBHGetVolParmsAsync (paramBlock 



PBHGetVInfoSync 
PBHGetVInfoAsync 
PBSetVInfo 

PBSetVInfoSync 
PBSetVInfoAsync 
PBHGetVolParms 



HParmBlkPtr; async: Boolean): 

HParmBlkPtr) : OSErr; 
HParmBlkPtr): OSErr; 
HParmBlkPtr; async: Boolean): 

HParmBlkPtr) : OSErr; 
HParmBlkPtr): OSErr; 
HParmBlkPtr; async: Boolean) 

HParmBlkPtr): OSErr; 
: HParmBlkPtr): OSErr; 



Manipulating the Default Volume 

FUNCTION PBGetVol (paramBlock: 

FUNCTION PBGetVolSync (paramBlock: 

FUNCTION PBGetVolAsync (paramBlock: 

FUNCTION PBSetVol (paramBlock: 

FUNCTION PBSetVolSync (paramBlock: 

FUNCTION PBSetVolAsync (paramBlock: 

FUNCTION PBHGetVol (paramBlock: 

FUNCTION PBHGetVolSync (paramBlock: 

FUNCTION PBHGetVolAsync (paramBlock: 

FUNCTION PBHSetVol (paramBlock: 

FUNCTION PBHSetVolSync (paramBlock: 

FUNCTION PBHSetVolAsync (paramBlock: 



ParmBlkPtr; async: Boolean): OSErr; 
ParmBlkPtr): OSErr; 
ParmBlkPtr) : OSErr; 

ParmBlkPtr; async: Boolean): OSErr; 

ParmBlkPtr) : OSErr; 

ParmBlkPtr): OSErr; 

WDPBPtr; async: Boolean) : OSErr; 

WDPBPtr) : OSErr; 

WDPBPtr) : OSErr; 

WDPBPtr; async: Boolean) : OSErr; 
WDPBPtr) : OSErr; 
WDPBPtr) : OSErr; 



File System Specification Routines 



Opening Files 

FUNCTION FSpOpenDF 

FUNCTION FSpOpenRF 



(spec: FSSpec; permission: SignedByte; 

VAR refNum: Integer) : OSErr; 
(spec: FSSpec; permission: SignedByte; 

VAR refNum: Integer): OSErr; 
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Creating and Deleting Files and Directories 



FUNCTION FSpCreate 

FUNCTION FSpDirCreate 
FUNCTION FSpDelete 



(spec: FSSpec; creator: OSType; . 
fileType: OSType; scriptTag: ScriptCode) 
OSErr; 

(spec: FSSpec; scriptTag: ScriptCode; 
VAR createdDirlD: Longint) : OSErr; 
(spec: FSSpec): OSErr; 



Accessing Information About Files and Directories 

FUNCTION FSpGetFInfo 
FUNCTION FSpSetFInfo 
FUNCTION FSpSetFLock 
FUNCTION FSpRstFLock 
FUNCTION FSpRename 



(spec: FSSpec; VAR fndrlnfo: FInfo) : OSErr; 
(spec: FSSpec; fndrlnfo: FInfo): OSErr; 
(spec: FSSpec): OSErr; 
(spec: FSSpec): OSErr; 

(spec: FSSpec; newName: Str255) : OSErr; 



Moving Files or Directories 

FUNCTION FSpCatMove 



(source: FSSpec; dest : FSSpec): OSErr; 



Exchanging the Data in Two Files 

FUNCTION FSpExchangeFiles (source: FSSpec; dest: FSSpec): OSErr; 



Creating File System Specifications 



FUNCTION FSMakeFSSpec 

FUNCTION PBMakeFSSpec 

FUNCTION PBMakeFSSpecSync 
FUNCTION PBMakeFSSpecAsync 

High-level HFS Routines 



(vRefNum: Integer; dirlD: Longint; 
fileName: Str255; VAR spec: FSSpec): OSErr; 

(paramBlock: HParraBlkPtr ; async: Boolean): 
OSErr; 

(paramBlock: HParmBlkPtr) : OSErr; 
(paramBlock: HParmBlkPtr) : OSErr; 



Opening Files 

FUNCTION HOpenDF 

FUNCTION HOpenRF 



(vRefNum: Integer; dirlD: Longint; 

fileName: Str255; permission: SignedByte; 

VAR refNum: Integer) : OSErr; 
(vRefNum: Integer; dirlD: Longint; 

fileName: Str255; permission: SignedByte; 

VAR refNum: Integer) : OSErr; 
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FUNCTION HOpen (vRefNum: Integer; dirlD: Longint; 

fileName: Str255; permission: SignedByte; 
VAR refNum: Integer) : OSErr; 

Creating and Deleting Files and Directories 

FUNCTION HCreate (vRefNum: Integer; dirlD: LongInt; 

fileName: Str255; creator: GSType; 

fileType: OSType) : OSErr; 
FUNCTION DirCreate (vRefNvim: Integer; parentDirlD: Longint; 

directoryName: Str255; 

VAR createdDirlD: Longint) : OSErr; 

FUNCTION HDelete (vRefNum: Integer; dirlD: Longint; 

fileName: Str255) : OSErr; 

Accessing Information About Files and Directories 

FUNCTION HGetFInfo (vRefNum: Integer; dirlD: Longint; 

fileName: Str255; VAR fndrlnfo: FInfo) : OSErr; 

FUNCTION HSetFInfo (vRefNum: Integer; dirlD: Longint; 

fileName: Str255; fndrlnfo: FInfo) : OSErr; 

FUNCTION HSetFLock (vRefNum: Integer; dirlD: Longint; 

fileName: Str25B) : OSErr; 

FUNCTION HRstFLock (vRefNum: Integer; dirlD: Longint; 

fileName: Str255) : OSErr; 

FUNCTION HRename (vRefNum: Integer; dirlD: Longint; 

oldName: Str255; newName: Str255) : OSErr; 

Moving Files or Directories 

FUNCTION CatMove (vRefNum: Integer; dirlD: Longint; 

oldName: Str255; newDirlD: Longint; 
newName: Str255) : OSErr; 

Maintaining Working Directories 

FUNCTION OpenWD (vRefNum: Integer; dirlD: Longint; 

procID: Longint; VAR wdRefNiim: Integer) : OSErr; 

FUNCTION CloseWD (wdRefNum: Integer) : OSErr; 

FUNCTION GetWDInfo (wdRefNum: Integer; VAR vRefNum: Integer; 

VAR dirlD: Longint; VAR procID: Longint): 

OSErr; 
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Low-Level HFS Routines 



Opening Files 



ruwt^iXUJM fbnupenDF 


(paramBlock: 


HParmBlkPtr; 


async : 


Boolean) : 




OSErr; 








FUNCTION PBHOpenDFSync 


(paramBlock: 


HParmBlkPtr) 


: OSErr; 




FUNCTION PBHOpenDFAsync 


{paramBlock: 


HParmBlkPtr) 


: OSErr ; 




FUNCTION PBHOpenRF 


(paramBlock: 


nt'a r mts 1 K r t r ; 


async : 


Boolean) : 




OSErr ; 








FUNCTION PBHOpenRFSync 


(paramBlock: 


HParmBlkPtr) 


: OSErr ; 




FUNCTION PBHOpenRFAsync 


(paramBlock: 


HParmBlkPtr) 


: OSErr; 




FUNCTION PBHOpen 


(paramBlock: 


HParmBlkPtr ; 


async : 


Boolean) : 




OSErr ; 








FUNCTION PBHOpenSync 


(paramBlock: 


HParmBlkPtr) 


: OSErr; 




FUNCTION PBHOpenAsync 


(paramBlock: 


HParmBlkPtr) 


: OSErr; 




Creating and Deleting Files and Directories 








FUNCTION PBHCreate 


(paramBlock: 


HParmBlkPtr; 


async: 


Boolean) : 




OSErr; 








FUNCTION PBHCreateSync 


(paramBlock: 


HParmBlkPtr) 


: OSErr ; 




FUNCTION PBHCreateAsync 


(paramBlock: 


HParmBlkPtr) 


: OSErr; 




FUNCTION PBDirCreate 


(paramBlock: 


HParmBlkPtr; 


async: 


Boolean) : 




OSErr; 








FUNCTION PBDirCreateSync 


(paramBlock: 


HParmBlkPtr) 


: OSErr; 




FUNCTION PBDirCreateAsync 


(paramBlock: 


HParmBlkPtr) 


: OSErr; 




FUNCTION PBHDelete 


(paramBlock: 


HParmBlkPtr; 


async : 


Boolean) : 




OSErr; 








FUNCTION PBHDeleteSync 


(paramBlock: 


HParmBlkPtr) 


: OSErr; 




FUNCTION PBHDeleteAsync 


(paramBlock: 


HParmBlkPtr) 


: OSErr; 




Accessing Information About Files and Directories 






FUNCTION PBGetCatlnfo 


(paramBlock: 


CInfoPBPtr; , 


async: Boolean) : ' 


FUNCTION PBGetCatlnfoSync 


(paramBlock: 


CInfoPBPtr) : 


OSErr ; 




FUNCTION PBGetCatlnfoAsync 


(paramBlock: 


CInfoPBPtr) : 


OSErr; 




FUNCTION PBSetCatlnfo 


(paramBlock: 


CInfoPBPtr; , 


async: Boolean) : i 


FUNCTION PBSetCatlnfoSync 


(paramBlock: 


CInfoPBPtr) : 


OSErr ; 




FUNCTION PBSetCatlnfoAsync 


(paramBlock: 


CInfoPBPtr) : 


OSErr; 




FUNCTION PBHGetFInfo 


(paramBlock: 


HParmBlkPtr; 


async : 


Boolean) : 



OSErr; 
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FUWCTtON PBHGetFInfoSync 
FUNCTION PBHGetFInfoAsync 
FUNCTION PBHSetFIn-fo 

FUNCTION PBHSetFInfoSync 
FUNCTION PBHSetFInfoAsync 
FUNCTION PBHSetFLock 

FUNCTION PBHSetFLockSync 
FUNCTION PBHSetFLockAsync 
FUNCTION PBHRstFLock 

FUNCTION PBHRstFLockSync 
FUNCTION PBHRstFLockAsync 
FUNCTION PBHRename 

FUNCTION PBHRenameSync 
FUNCTION PBHRenameAsync 

Moving Files or Directories 

FUNCTION PBCatMove 
FUNCTION PBCatMoveSync 
FUNCTION PBCatMoveAsync 



(paramBlock: 
(parainBlock: 

(paramBlock: 
OSErr; 
(paramBlock: 
(paramBlock: 

(paramBlock: 
OSErr ; 

(paramBlock: 

(paramBlock: 

(paramBlock: 
OSErr ; 

(paramBlock: 

(paramBlock: 

(paramBlock: 
OSErr; 

(paramBlock: 
(paramBlock: 



HParmBlkPtr) : OSErr; 
HParmBlkPtr) : OSErr; 
HParmBlkPtr; async: Boolean) : 

HParmBlkPtr): OSErr; 
HParmBlkPtr): OSErr; 
HParmBlkPtr; async: Boolean) : 

HParmBlkPtr) : OSErr; 
HParmBlkPtr) : OSErr; 
HParmBlkPtr; async: Boolean) : 

HParmBlkPtr): OSErr; 
HParmBlkPtr): OSErr; 
HParmBlkPtr; async: Boolean) 

HParmBlkPtr) : OSErr; 
HParmBlkPtr) : OSErr; 



(paramBlock: CMovePBPtr; async: Boolean): OSErr; 
(paramBlock: CMovePBPtr) : OSErr; 
(paramBlock: CMovePBPtr) : OSErr; 



Maintaining Working Directories 

FUNCTION PBOpenWD 
FUNCTION PBOpenWDSync 
FUNCTION PBOpenWDAsync 
FUNCTION PBCloseWD 
FUNCTION PBCloseWDSync 
FUNCTION PBCloseWDAsync 
FUNCTION PBGetWDInfo 
FUNCTION PBGetWDInfoSync 
FtJNCTION PBGetWDInfoAsync 

Searching a Catalog 

FUNCTION PBCatSearch 

FUNCTION PBCatSearchSync 
FUNCTION PBCatSearchAsync 



(paramBlock: WDPBPtr; async: Boolean): OSErr; 

(paramBlock: WDPBPtr) : OSErr; 

(paramBlock; WDPBPtr) : OSErr; 

(paramBlock: WDPBPtr; async: Boolean): OSErr; 

(paramBlock: WDPBPtr) : OSErr; 

(paramBlock: WDPBPtr) : OSErr; 

(paramBlock: WDPBPtr; async: Boolean): OSErr; 

(paramBlock: WDPBPtr): OSErr; 

(paramBlock: WDPBPtr): OSErr; 



(paramBlock: HParmBlkPtr; async: Boolean) 
OSErr; 

(paramBlock: HParmBlkPtr) : OSErr; 

(paramBlock: HParmBlkPtr) : OSErr; 
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Exchanging the Data in Two Files 

FUNCTION PBExchangePiles (para^Block: HPamaikPtr async: Boolean) 

OSErr; 

FUNCTION PBExchangeFilesSync(paramBlock: HParmBlkPtr) : OSErr- 
FUNCTION PBExchangeFilesAsync 

(paramBlock: HParmBlkPtr): OSErr; 

Shared Environment Routines 



Opening Files While Denying Access 

FUNCTION PBHOpenDeny (paramBlock: 



FUNCTION PBHOpenDenySync 
FUNCTION PBHOpenDenyAsync 
FUNCTION PBHOpenRFDeny 

FUNCTION PBHOpenRFDenySync 



OSErr; 

(paramBlock: 

(paramBlock: 

(paramBlock: 
OSErr; 

(paramBlock: 
FUNCTION PBHOpenRFDenyAsync (paramBlock: 

Locking and Unlocking File Ranges 

FUNCTION PBLockRange (paramBlock: 

FUNCTION PBLockRangeSync (paramBlock: 

FUNCTION PBLockRangeAsync (paramBlock : 

FUNCTION PBUnlockRange {paramBlock: 

FUNCTION PBUnlockRangeSync (paramBlock: 

FUNCTION PBUnlockRangeAsync (paramBlock: 



ManipulaHng Share Points 

FUNCTION PBShare 

FUNCTION PBShareSync 
FUNCTION PBShareAsync 
FUNCTION PBUnshare 

FUNCTION PBUnshareSync 
FUNCTION PBUnshareAsync 
FUNCTION PBGetUGEntry 

FUNCTION PBGetUGEntrySync 
FUNCTION PBGetUGEntryAsync 



(paramBlock: 
OSErr; 

(paramBlock: 

(paramBlock: 

(paramBlock; 
OSErr; 

(paramBlock: 

(paramBlock: 

(paramBlock: 
OSErr; 

(paramBlock: 

(paramBlock: 



HParmBlkPtr; async: Boolean) 

HParmBlkPtr) : OSErr; 
HParmBlkPtr) : OSErr; 
HParmBlkPtr; async: Boolean); 

HParmBlkPtr) : OSErr; 
HParmBlkPtr) : OSErr; 



ParmBlkPtr; async: Boolean): OSErr; 
ParmBlkPtr) : OSErr; 
ParmBlkPtr) : OSErr; 

ParmBlkPtr; async: Boolean): OSErr; 
ParmBlkPtr) : OSErr; 
ParmBlkPtr) : OSErr; 



HParmBlkPtr; async: Boolean): 

HParmBlkPtr) : OSErr; 
HParmBlkPtr) : OSErr; 
HParmBlkPtr; async: Boolean): 

HParmBlkPtr) : OSErr; 
HParmBlkPtr) : OSErr; 
HParmBlkPtr; async: Boolean): 

HParmBlkPtr) : OSErr; 
HParmBlkPtr).: OSErr; 
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Contrdlling Directory Access 

FUNCTION PBHGetDirAccess (paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

FUNCTION PBHGetDirAccessSync (paramBlock: HParmBlkPtr): OSErr; 

FUNCTION PBHGetDirAccessAsync 

(paramBlock: HParmBlkPtr): OSErr; 

FUNCTION PBHSetDirAccess (paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

FUNCTION PBHSetDirAccessSync (paramBlock: HParmBlkPtr): OSErr; 

FUNCTION PBHSetDirAccessAsync 

(paramBlock: HParmBlkPtr): OSErr; 

Mounting Volumes 

FUNCTION PBGetVolMountlnfoSize 

(paramBlock: ParmBlkPtr) : OSErr; 

FUNCTION PBGetVolMquntlnfo (paramBlock: ParmBlkPtr): OSErr; 

FUNCTION PBVolumeMount (paramBlock: ParmBlkPtr): OSErr; 

Controlling Login Access 

FUNCTION PBHGetLoglnlnfo (paramBlock: HParmBlkPtr; async: Boolean): 

OSErr ; 

FUNCTION PBHGetLoglnlnfoSync (paramBlock: HParmBlkPtr): OSErr; 

FUNCTION PBHGetLoglnlnfoAsync 

(paramBlock: HParmBlkPtr): OSErr; 

(paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

(paramBlock: HParmBlkPtr): OSErr; 
(paramBlock: HParmBlkPtr): OSErr; 
(paramBlock: HParmBlkPtr; async: Boolean): 
OSErr ; 

(paramBlock: HParmBlkPtr): OSErr; 
(paramBlock: HParmBlkPtr) : OSErr; 

(paramBlock: HParmBlkPtr; async: Boolean): 
OSErr ; 

(paramBlock: HParmBlkPtr) : OSErr; 

(paramBlock: HParmBlkPtr) : OSErr; 



FUNCTION PBHMapID 

FUNCTION PBHMapIDSync 
FUNCTION PBHMapIDAsync 
FUNCTION PBHMapName 

FUNCTION PBHMapNameSync 
FUNCTION PBHMapNameAsync 

Copying and Moving Files 

FUNCTION PBHCopyFile 

FUNCTION PBHCopyFileSync 
FUNCTION PBHCopyFileAsync 
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FUNCTION PBHMoveRenan,e (paramBlock: HParmBlkPtr; async : Boolean) 

OSErr; 

FUNCTION. PBHMoveRenameSync (paramBlock: HParmBlkPtr): OSErr- 
FUNCTION PBHMoveRenameAsync (paramBlock: HParmBlkPtr): OSErr! 

File ID Routines 

Resolving File ID References 

FUNCTION PBResolveFilelDRef (paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

FUNCTION PBResolveFilelDRefSync 

(paramBlock: HParmBlkPtr): OSErr; 
FUNCTION PBResolveFil'elDRefAsync 

(paramBlock: HParmBlkPtr): OSErr; 

Creating and Deleting File ID References 

FUNCTION PBCreateFilelDRef (paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

FUNCTION PBCreateFilelDRefSync 

(paramBlock: HParmBlkPtr) : OSErr; 
FUNCTION PBCreateFilelDRefAsync 

(paramBlock: HParmBlkPtr): OSErr- 
FUNCTION PBDeleteFilelDRef (paramBlock: HParmBlkPtr; async: ' Boolean) : 

OSErr; 

FUNCTION PBDeleteFilelDRefSync 

(paramBlock: HParmBlkPtr) : OSErr; 
FUNCTION PBDeleteFilelDRefAsync 

(paramBlock: HParmBlkPtr): OSErr; 

Foreign File System Routine s 

Accessing Privilege Information in Foreign File Systems 

FUNCTION PBGetForeignPrivs (paramBlock: HParmBlkPtr; async: Boolean): 

OSErr; 

FUNCTION PBGetForeignPrivsSync 

(paramBlock: HParmBlkPtr): OSErr; 
FUNCTION PBGetForeignPrivsAsync 

(paramBlock: HParmBlkPtr): OSErr; 
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FUNCTION PBSetForeignPrivs (paramBlock: HParmBlkPtr; async: Boolean) : 
; OSErr; 

FliNCTION PBSetForeignPrivsSync 

(paramBlock: HParmBlkPtr): OSErr; 

FUNCTION PBSetForeignPrivsAsync 

(paramBlock: HParmBlkPtr): OSErr; 

Utjlity Routines 



Obtaining Queue Headers 

FUNCTION GetFSQHdr 
FUNCTION GetVCBQHdr 
FUNCTION GetDrvQHdr 



QHdrPtr; 
QHdrPtr; 
QHdrPtr; 



Adding a Drive 

PROCEDURE AddDrive 



(drvrRefNum: Integer; drvNum: Integer; 
qEl: DrvQElPtr); 



Obtaining File Control Block Information 

FUNCTION PBGetFCBInfo (paramBlock: FCBPBPtr; async: Boolean): OSErr; 

FUNCTION PBGetFCBInfoSync (paramBlock: FCBPBPtr): OSErr; 

FUNCTION PBGetFCBInfoAsync (paramBlock: FCBPBPtr): OSErr; 

Application-Defined Routine 

Completion Routines 

PROCEDURE MyCompletionProc; 

C Summary 
Constants 



/*Gestalt constants*/ 
#def ine gestaltFSAttr ■ f s 

#define gestaltFullExtFSDispatching 0 
#define gestaltHasFSSpecCalls 1 



/*file system attributes selector*/ 
/♦exports HFSDispatch traps*/ 
/* supports FSSpec records*/ 
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/^directory IDs*/ 
enum { 

fsRtParlD 

f sRtDirib 



= 1, /*directory ID of root directory's parent*/ 

= 2}; /*directpry ID of volume's root directory*/ 



/*values for requesting file read/write permissions*/ 
enum { 

f sCurPerm = o , 

fsRdPerm = 

f sWrPerm = 2 , 

fsRdWrPerm = 3^ 

fsRdWrShPerm = 4); 



/*whatever permission is allowed*/ 
/*read permission*/ 
/*write permission*/ 
/*exclusive read/write permission*/ 
/*shared read/write permission*/ 



I 



/*file mark positioning modes*/ 
enum { 

fsAtMark = 0, 

fsFromStart = l, 

f sFromLEOF = 2 , 

f sFromMark = 3 ^ 

rdVerify =64}; 



fa 

CO 
CD 



/*at current mark) 

/*set mark relative to beginning of file*/ 
/*set mark relative to logical end-of-f ile*/ 
/*set mark relative to current mark*/ 
/*add to above for read-verify*/ 



/*values for ioSearchBits in PBCatSearch parameter block*/ 
enum { 



fsSBPartialName 
f sSBFullName. 
f sSBFlAttrib 
fsSBNegate 

/*for files only*/ 

enurh { 

fsSBFlFndrlnfo 

fsSBFlLgLen 

fsSBFlPyLen 

fsSBFlRLgLen 

fsSBFlRPyLen 

fsSBFlCrOat 

• fsSBFlMdDat 
fsSBFlBkDat 
fsSBFlXFndrlnfo 
fsSBFlParlD 



= 1/ /* substring of name*/ 

= 2, /*full name*/ 

= 4, /*directory flag; software lock flag*/ 

= 16384); /*reverse match status*/ 



8, /*Finder file info*/ 

32, /*lpgical length of data fork*/ 

64, /*physical length of data fork*/ 

128, /*logical length of resource fork*/ 

256, /*physical length of resource fork*/ 

512, /*file creation date*/ 

1024, /*file modification date*/ 

2048, /*file backup date*/ 

4096, /*more Finder file info*/ 

8192}; /*file*s parent ID*/ 
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/*fpr directories only*/ 
ehuip { 

. "fsSBDrUsrWds = 8, 

f&SBDrNmFls = 16, 

fsSBDrCrDat = 512, 

fsSBDrMdDat = 1024, 

fsSBDrBkDat = 2048, 

f sSBDrFndrlnfo = 4096, 

fsSBDrParlD = 8192}; 



/*Finder directory info*/ 
/♦number of files in directory*/ 
/♦directory creation date*/ 
/♦directory modification date*/ 
/♦directory backup date*/ 
/*more Finder directory info*/ 
/♦directory's parent ID*/ 



/♦value of vMForeignPrivID in file attributes buffer*/ 

enum [fsUnixPriv =1); /*A/UX privilege model*/ 

/♦bit positions in vMAttrib field of GetVolParmsInf oBuf f er*/ 
enum { 

bHasBlankAccessPrivileges 







4, 


/*volume supports inherited privileges*/ 


bHasBTreeMgr 




5, 


/♦reserved*/ 


bHasFilelDs 




6, 


/♦volume supports file ID functions^/ 


bHasCatSearch 




7, 


/♦volume supports .PBCatSearch^/ 


bHasUserGroupList 




8, 


/♦volume supports AFP privileges^/ 


bHasPersonalAccessPrivileges 








9, 


. /♦local file sharing is enabled*/ 


bHasFolderLock 




10, 


/♦volume supports locking of folders*/ 


bHasShortName 




11, 


/♦volume supports shorter volume name*/ 


bHasDesktopMgr 




12, 


/♦volume supports Desktop Manager^/ 


bHasMoveRename 




13, 


/♦volume supports _MoveRename^/ 


bHasCopyFile 




14, 


/♦volume supports _CopyFile*/ 


bHasOpenDeny 




15, 


/♦volume supports shared access modes^/ 


bHasExtFSVol 




16, 


/♦volume is external file system volume^/ 


bNoSysDir 




17, 


/♦volume has no system directory*/ 


bAccessCntl 




18, 


/*volume supports AFP access control*/ 


bNoBootBlks 




19, 


/*volume is not a startup volume*/ 


bNoDeskltems 




20, 


/*do not place objects on the desktop*/ 


bNoSwitchTo 




25, 


/*do not switch launch to applications*/ 


bTrshOf fLine 




26, 


/*zoom volume when it is unmounted*/ 


bNoLclSync 




27, 


/*don*t let Finder change mod. date*/ 


bNoVNEdit 




28, 


/*lock volume name*/ 


bNoMiniFndr 




29, 


/* reserved; always 1*/ 


bLocalWList 




30, 


/*use shared volume handle for window */ 
/* list*/ 


bLimitFCBs 




• 31}; 


/*limit file control blocks*/ 
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/*media type in remote mounting information/* 
enum {AppleShareMediaType 

= 'afpm*}; /*an AppleShare volume*/ 



/*user authentication methods in AFP remote mounting information*/ 
enum { 

= 1/ /*guest status; no password needed*/ 

= 2, /*8-bfyte password*/ 

= 3, /*encrypted 8-byte password*/ 

= 6 } ; / * two-way random encrypt ion ; * / 

/* authenticate both user and server*/ 



kNoUserAuthentication 
kPas sword 
kEncrypt Password 
kTwoWay Encrypt Pas sword 



I 



Data Types 



0) 
3 
fi) 

to 



File System Specification Record 

'Struct FSSpec { 

short vRefNum; 
long parlD; 
Str63 name; 

}; 



/*file system specification*/ 
/* volume reference number*/ 
/*directory ID of .parent directory*/ 
/* filename or directory name*/ 



typedef struct FSSpec FSSpec; 
typedef FSSpec *FSSpecPtr; 
typedef FSSpecPtr *FSSpecHandle; 

File and Directory Parameter Blocks 



union ParamBlockRec { 
lOParam 
FileParam 
VolumeParam 
CntrlParam 
SlotDevParam 
MultiDevParam 

}; 



ioParam; 

f ileParam; 

volumeParam; 

cntrlParcun; 

SlotDevParam; 

raultiDevParam; 



typedef union ParamBlockRec ParamBlockRec; 
typedef ParamBlockRec *ParmBlkPtr; 
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#define ParamBlockHeader \ 



■ QElemPtr 
short 
short 
Ptr 

ProcPtr 
OSErr 
StringPtr 
short 



qLink ; 

qType; 

ioTrap; 

ioCmdAddr ; 

ioCompletion; 

ioResult; 

ioNamePtr; 

ioVRefNum; 



/*next queue entry* /\ 
/* queue type*/\ 
/*routine trap*/\ 
/♦routine address* /\ 
/♦completion routine*/\ 
/♦result code*/\ 
/♦pointer to pathname* /\ 
/♦volume specification*/ 



struct lOParam { 

ParamBlockHeader 



short 


ioRefNum; 


/*file reference number*/ 


char 


ioVersNum; 


/♦version number*/ 


char 


ioPermssn; 


/♦read/write permission*/ 


Ptr 


ioMisc; 


/♦miscellaneous^/ 


Ptr 


ioBuf fer ; 


/♦data buffer*/ 


long 


ioReqCount ; 


/♦requested number of bytes*/ 


long 


ioActCount ; 


/*actual number of bytes*/ 


short 


ioPosMode; 


/♦positioning mode and newline char.*/ 


long 


ioPosOf f set ; 


/ *positioning offset*/ 



}; 

typedef struct lOParam lOParam; 
struct FileParam { 



ParamBlockHeader 




short 


ioFRefNum; 


/*file reference number*/ 


char 


ioFVersNum; 


/*file version number (unused)*/ 


char 


fillerl; 


/♦reserved* / 


short 


ioFDirlndex; 


/*directory index*/ 


unsigned char 


ioFlAttrib; 


/*file attributes*/ 


unsigned char 


ioFlVersNum; 


/♦file version number (unused)*/ 


FInfo 


ioFlFndrlnfo; 


/♦information used by the Finder*/ 


unsigned long 


ioFlNum; 


/♦File ID*/ 


unsigned short 


ioFlStBlk; 


/♦first alloc, blk. of data fork*/ 


long 


ioFlLgLen; 


/♦logical EOF of data fork*/ 


long 


ioFlPyLen; 


/♦physical EOF of data fork^/ 


unsigned short 


ioFlRStBlk; 


/♦first alloc, blk. of resource fork*/ 


long 


ioFlRLgLen; 


/*logical EOF of resource fork*/ 


long 


ioFlRPyLen; 


/♦physical EOF of resource fork*/ 


unsigned long 


ioFlCrDat; 


/*date and time of creation*/ 


unsigned long 


ioFlMdDat ; 


/*date and time of last modification*/ 



}; 



typedef struct FileParam FileParam; 
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struct VoliomeParam ( 



ParamBlockHeader . 




long 




filler2; 


/* reserved*/ 


short 




ioVolIndex; 


/ *voluine index* / 


unsigned 


long 


ioVCrDate; 


/*date and time of initialization*/ 


unsigned 


long 


ioVLsBkUp; 


/*date and time of last modification*/ 


unsigned 


short 


ioVAtrb; 


/*volume attributes*/ 


unsigned 


short 


ioVNmFls; 


/*number of files in root directory*/ 


unsigned 


short 


ioVDirSt; 


/*first block of directory*/ 


short 




ioVBlLn; 


/*length of directory in blocks*/ 


unsigned 


short 


ioVNmAlBlks; 


/*number of allocation blocks*/ 


long 




ioVAlBlkSiz; 


/*size of allocation blocks*/ 


long 




ioVClpSiz; 


/*number of bytes to allocate*/ 


unsigned 


short 


ioAlBlSt; 


/*first block in block map*/ 


unsigned 


long 


ioVNxtFNum; 


/*next unused file ID*/ 


unsigned 


short 


ioVFrBlk; 


/*number of unused allocation blocks*/ 



typedef struct VolumeParam VolumeParam; 



union HParamBlockRec { 
HlOParam 
HFileParam 
HVolumeParam 
AccessParam 
Ob j Pa ram 
Copy Par am 
WDParam 
FIDParam 
CSParam 

ForeignPrivParam 

); 



/*HFS parameter block*/ 

ioParam; 
f ileParam; 
volumeParam; 
accessParam; 
obj Pa ram ; 
copyParam; 
wdParam; 
f idPa rami- 
es Par am ; 

f oreignPrivParam; 



typedef union HParamBlockRec HParamBlockRec; 
typedef HParamBlockRec *HParmBlkPtr ; 



struct HlOParam .{ 

ParamBlockHeader 

short 

char 

char 

Ptr 

Ptr 

long 



ioRefNum; /*file reference number*/ 

ioVersNum; /*version number*/ 

ioPermssn; /*read/write permission*/ 

ioMisc; /*miscellaneous*/ 

ioBuffer; /*data buffer*/ 

ioReqCount; /*requested number of bytes*/ 
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'long ioActCount; 
-short ioPosMode; 
long ioPosOffset; 

} ; 

typedef struct HlOParam HlOParam; 
struct HFileParam { 



ParairiBlockHeader 




short 




XOr KG tXNUlil f 


char 




ioFVersNum; 


char 




fillerl; 


short 




ioFDir Index; 


char 




ioFlAttrib; 


char 




ioFlVersNum; 


FInfo 




ioFlFndrlnfo; 


long 




ioDirlD; 


unsigned 


short 


ioFlStBlk; 


long 




ioFlLgLen; 


long 




ioFlPyLen; 


unsigned 


short 


ioFlRStBlk; 


long 




ioFlRLgLen; 


long 




ioFlRPyLen; 


unsigned 


long 


ioFlCrDat ; 


unsigned 


long 


ioFlMdDat ; 



}; 

typedef struct HFileParam HFileParam; 
struct HVolumeParam { 



ParamBlockHeader 




Icing 


filler2; 


short 


ioVol Index; 


unsigned long 


ioVCrDate; 


unsigned long 


ioVLsMod; 


short 


ioVAtrb; 


unsigned short 


ioVNmFls; 


short 


ioVBitMap; 


short 


ioAllocPtr; 


unsigned short 


ioVNitiAlBlks; 


long 


ioVAlBlkSiz; 


long 


ioVClpSiz; 


short 


ioAlBlSt; 


long 


ioVNxtCNID; 
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/^actual number of bytes*/ 
/*positioning mode and newline char.*/ 
/*positioning offset*/ 



/*file reference number*/ 

/*file version number (unused)*/ 

/* reserved*/ 

/♦directory index*/ 

/*file attributes*/ 

/*file version number (unused)*/ 

/♦information used by the Finder*/ 

/♦directory ID or file ID*/ 

/♦first alloc, blk. of data fork*/ 

/*logical EOF of data fork*/ 

/♦physical EOF of data fork*/ 

/*first alloc, blk. of resource fork*/ 

/*logical EOF of resource fork*/ 

/*physical EOF of resource fork*/ 

/♦date and time of creation*/ 

/*date and time of last modif ication^ / 



/♦reserved^/ 
/♦volume index*/ 

/*date and time of initialization*/ 
/♦date and time of last modification*/ 
/*vol\me attributes*/ 
/♦number of files in root directory^/ 
/♦first block of volume bitmap^/ 
/♦first block of next new file*/ 
/♦number of allocation blocks*/ 
/♦size of allocation blocks^/ 
/♦default clump size*/ 
/♦first block in volume map*/ 
/♦next unused node IX)*/ 
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unsigned short 

unsigned short 

short . 

short 

short 

unsigned long 

unsigned short 

•long 

long 

long 

long 



ioVFrBlk; 

ioVSigWord; 

ioVDrvInf o; 

ioVDRefNura; 

ioVFSID; 

ioVBkUp; 

ioVSeqNum; 

ioVWrCnt; 

ioVFilCnt; 

ioVDirCnt ; 

ioVFndrInfo[8] 



/*nuinber of unused allocation blocks*/ 
/♦volume signature*/ 
/*drive number*/ 
/*driver reference number*/ 
/*f ile-system identifier*/ 
/*date and time of last backup*/ 
/*used internally*/ 
/*volume write count*/ 
/*number of files on volume*/ 
/*n\Hnber of directories on volume*/ 
; /*inf ormation used by the Finder*/ 



I 



2! 



pa 

(O 
(D 



typedef struct HVolumeParam HVolumeParam; 



struct AccessParam { 

ParamBlockHeader 

short 

short 

short 

char 

char 

long 

long 

long 

long 

); 



filler3; 
i oDeny Modes ; 
filler4; 
fillers; 
ioACUser ; 
fillerG; 
ioACOwnerlD; 
ioACGroupID; 
ioACAccess; 



/* reserved*/ 

/♦access mode information*/ 

/♦reserved*/ 

/*reserved* / 

/*user access rights*/ 

/♦reserved*/ 

/*owner ID*/ 

/*group ID*/ 

/*directory access rights*/ 



typedef struct AccessParam AccessParam; 



struct ObjParam { 

ParamBlockHeader 

short 

short 

StringPtr 

long 

long 

long 

); 



filler?; 
ioObj Type; 
ioObjNamePtr ; 
ioObjID; 
ioReqCount ; 
ioAct Count; 



/♦reserved*/ 
/♦function code*/ 

/*ptr to returned creator /group name*/ 
/♦creator /group ID*/ 
/*size of buffer area*/ 
/♦length of data^/ 



typedef struct ObjParam ObjParam; 
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struct ICopyParam ( 

..ParamBlockHeader 



short 


ioDstVRefNum; 


short 


fillers; 


StringPtr 


ioNewName; 


StringPtr 


ioCopyName; 


long 


ioNewDirlD; 


long - 


fillerl4; 


long 


fillerlS; 


long. 


ioDirlD; 



/♦destination volume identifier*/ 
/* reserved*/ 

/♦pointer to destination pathname*/ 
/♦pointer to optional name*/ 
/♦destination directory ID*/ 
/♦reserved*/ 
/♦reserved^/ 

/♦directory ID or file ID*/ 



}; 



typedef struct CopyParam CopyParam; 



struct vmParam { 

ParamBlockHeader 

short 

short 

long 

short 

short 

long 

long 

long 

long 

}; 



fillers ? 
ioWDIndex; 
ioWDProcID; 
ioWDVRefNum; 
fillerlO; 
fillerll; 
fillerl2; 
fillerl3i 
ioWDDirlD; 



/♦reserved^/ 

/♦working directory index*/ 

/♦working directory user identifier^/ 

/♦working directory's vol. ref . num.*/ 

/♦reserved*/ 

/♦reserved^ / 

/♦reserved*/ 

/♦reserved^/ 

/♦working directory's directory IV*/ 



typedef struct WDParam WDParam; 



struct FIDParam { 

ParamBlockHeader 
long 

StringPtr 

long 

long 

long 

long 

long 

short 

long 

}; 



fillerl; 
ioDestNamePtr; 
filler2; 
ioDestDirlD; 
fillers ; 
filler4; 
ioSrcDirlD; 
fillers; 
ioFilelD; 



/♦reserved^/ 

/♦pointer to destination filename^/ 
/♦reserved^/ 

/♦destination parent directory ID*/ 

/♦reserved^/ 

/♦reserved^/ 

/♦source parent directory ID*/ 

/♦reserved^/ 

/♦file ID*/ 



typedef struct FIDParam FIDParam; 
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struct CSParam { 

ParamBlockHeader 

FSSpecPtr 

long 

long 

long 

CInfoPBPtr 
ClnfoPBPtr 
long 

CatPositionRec 

Ptr 

long 

)? 



ioMatdhPtr; 
ioReqMatchCount ; 
ioActMatchCount ; 
ioSearchBits ; 
ioSearchInf ol ; 

ioSearchInf o2 ; 

ioSearchTime; 
ioCatPosition; 
ioOptBuf f er; 
ioOptBuf Size; 



/^pointer to array of matches*/ 
/*max number of matches to return*/ 
/*actual number of matches*/ 
/*enable bits for matching rules*/ 
/*pointer to values and lower */ 
/* bounds*/ 

/*pointer to masks and upper */ 
/* bounds*/ 

/*maximum time to search*/ 
/*current catalog position*/ 
/*pointer to optional read buffer*/ 
/*length of optional read buffer*/ 



typedef struct CSParam CSParam; 

struct ForeignPrivParam { 
ParamBlockHeader 

long fillerl; 

long filler2; 

Ptr ioForeignPrivBuf f er ; 

long ioForeignPrivReqCount ; 

long ioForeignPrivActCount ; 

long fillers ; 

long ioForeignPrivDirlD; 

long ioForeignPrivInf ol ; 

long ioForeignPrivInf o2 ; 

long ioForeignPrivInf o3 ; 

long ioForeignPrivInf o4 ; 

); 



/*reserved*/ 
/*reserved*/ 

/♦privileges data buffer*/ 
/*size of buffer*/ 
/♦amount of buffer used*/ 
/♦reserved*/ 

/♦parent directory ID of foreign */ 
/* file or directory*/ 
/♦privileges data*/ 
/♦privileges data*/ 
/♦privileges data*/ 
/♦privileges data*/ 



typedef struct ForeignPrivParam ForeignPrivParam; 
typedef ForeignPrivParam *ForeignPrivParamPtr ; 
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CatalQg'lnformation Parameter Blocks 

eniim {hFilelnfo, dirlnfo} ; 
typedef 'Unsigned char CInfoType; 

union CInfoPBRec { /*catalog information parameter block* 

HFilelnfo hFilelnfo; 
Dirlnfo dirlnfo; 

); 

typedef union CInfoPBRec CInfoPBRec; 
typedef CInfoPBRec *CInfoPBPtr; 

struct HFilelnfo { 



ParamBlockHeader 






short 




ioFRefNum; 


/*file reference number*/ 


char 




ioFVersNum; 


/♦version number*/ 


char 




fillerl; 


/♦reserved*/ 


short 




ioFDirlndex; 


/*file index*/ 


char 




ioFlAttrib; 


/*file attributes*/ . - 


char 




ioACUser; 


/♦directory access rights*/ 


FInfo 




ioFlFndrlnfo; 


/♦information used by the Finder*/ 


long 




ioDirlD; 


/♦directory ID or file ID*/ 


unsigned 


short 


ioFlStBlk; 


/*first alloc, blk. of data fork*/ 


long 




ioFlLgLen; 


/*logical EOF of data fork*/ 


long 




ioFlPyLen; 


/♦physical EOF of data fork*/ 


unsigned 


short 


ioFlRStBlk; 


/♦first alloc, blk. of resource fork^/ 


long 




ioFlRLgLen; 


/♦logical EOF of resource fork^/ 


long 




ioFlRPyLen; 


/♦physical EOF of resource fork*/ 


unsigned long 


ioFlCrDat ; 


/*date and time of creation*/ 


unsigned 


long 


ioFlMdDat; 


/*date and time of last modification*/ 


unsigned 


long 


ioFlBkDat ; 


/♦date and time of last backup*/ 


FXInfo 




ioFlXFndrlnfo; 


/♦additional Finder information*/ 


long 




ioFlParlD; 


/*file parent directory ID (integer)*/ 


long 




ioFlClpSiz; 


/♦file's clump size*/ 



}; 



typedef struct HFilelnfo HFilelnfo; 

struct Dirlnfo { 

ParamBlockHeader 

short ioFRefNum; /*file reference number*/ 

short fillerl; /*reserved*/ 

short ioFDirlndex; /*directory index*/ 
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char 
char 
DInfo 
long 

unsigned short 
short 

unsigned long 
unsigned long 
unsigned long 
DXInfo 
long 



ioFlAttrib; 
filler2; 
ioDrUsrWds ; 
ioDrDirlD; 
ioDrNinFls; 
fillers [9] ; 
ioDrCrDat ; 
ioDrMdDat ; 
ioDrBkDat ; 
ioDrFndrlnfo; 
ioDrParlD; 



/♦directory attributes*/ 
/* reserved*/ 

/* information used by the Finder*/ 

/♦directory ID*/ 

/♦number of files in directory*/ 

/♦reserved*/ 

/♦date and time of creation^/ 
/♦date and time of last modif ication^/ 
/♦date and time of last backup*/ 
/♦additional Finder information*/ 
/♦directory's parent directory ID^/ 



}; 



typedef struct Dirlnfo Dirlnfo; 

Catalog Position Record 

struct CatPositionRec { 

long initialize; 
short priv[6] ; 

}; 



/♦catalog position record*/ 
/♦starting point^/ 
/♦private data*/ 



typedef struct CatPositionRec CatPositionRec; 
Catalog Move Parameter Block 



CMovePBRec { 




/♦catalog move parameter block^/ 


QElemPtr 


qLink; 


/♦next queue entry^/ 


short 


qType; 


/♦queue type*/ 


short 


ioTrap; 


/♦routine trap^/ 


Ptr 


ioCmdAddr; 


/♦routine address^/ 


ProcPtr 


ioCompletion; 


/♦completion routine^/ 


OSErr 


ioResult ; 


/♦result code*/ 


StringPtr 


ioNamePtr; 


/♦pointer to pathname^/ 


short 


ioVRefNum; 


/♦volume specification*/ 


long 


fillerl; 


/♦reserved^/ 


StringPtr 


ioNewName; 


/♦name of new directory*/ 


long 


filler2; 


/*reserved*/ 


long 


ioNewDirlD; 


/♦directory ID of new directory ♦/ 


long 


fillers [2] ; 


/♦reseirved*/ 


long 


ioDirlD; 


/*directory ID of current directory*/ 



}; 



typedef struct CMovePBRec CMovePBRec; 
typedef CMovePBRec ♦CMovePBPtr; 
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Working Directory Parameter Block 

struct WDPBRec { 



QEleinPtr 




short 


qiype, 


short 




Ptr 




ProcPtr 


ioCompletion; 


OSErr 


ioResult ; 


StringPtr 


ioNamePtr; 


short 


ioVRefNum; 


short 


fillerl; 


short 


ioWDIndex; 


long 


ioWDProcID; 


short 


ioWDVRefNiom; 


short 


filler2[7] ; 


long 


ioWDDirlD; 



}; 



/^working directory parameter block*/ 

/*next queue entry*/ 

/* queue type*/ 

/*routine trap*/ 

/*routine address*/ 

/* completion routine*/ 

/*result code*/ 

/♦pointer to pathname*/ 

/*volvune specification*/ 

/*reserved*/ 

/♦working directory index*/ 
/♦working directory user identifier*/ 
/* working directory's vol. ref. num.*/ 
/*reserved*y 

/♦working directory's directory ID*/ 



typedef struct WDPBRec WDPBRec; 
typedef WDPBRec *WDPBPtr; 

File Control Block Parameter Block 



struct 



FCBPBRec { 




/♦file control block parameter block*/ 


QElemPtr 


qLink; 


/♦next queue entry ♦/ 


short 


qType; 


/♦queue type^/ 


short 


ioTrap; 


/♦routine trap*/ 


Ptr 


ioCmdAddr ; 


/♦routine address^/ 


ProcPtr 


ioCompletion; 


/♦completion routine*/ 


OSErr 


ioResult; 


/*result code*/ 


StringPtr 


ioNamePtr; 


/♦pointer to pathname^/ 


short 


ioVRefNum; 


/♦volume specif ication^/ 


short 


ioRefNum; 


/♦file reference number^/ 


short 


filler; 


/♦reserved*/ 


short 


ioFCBIndx; 


/♦FCB index^/ 


short 


fillerl; 


/♦reserved^/ 


long 


ioFCBFlNm; 


/♦file ID*/ 


short 


ioFCBFlags; 


/♦flags*/ 


\insigned short 


ioFCBStBlk; 


/♦first allocation block of file*/ 


long 


ioFCBEOF ; 


/♦logical end-Of-f ile^/ 


long 


ioFCBPLen; 


/♦physical end-of -f ile^/ 


long 


ioFCBCrPs ; 


/♦position of the file mark*/ 


short 


ioFCBVRefNum; 


/* volume reference number*/ 
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long 
long 



ioFCBClpSiz; 
ioFCBParlD; 



/♦file's clump size*/ 
/♦parent directory ID*/ 



}; 

typedef struct FCBPBRec FCBPBRec; 
typedef FCBPBRec *FCBPBPtr; 

Volume Attributes Buffer 

struct GetVolParmsInf oBuf f er ( 

short vMVersion; 
long vMAttrib; 
Handle vMLocalHand ; 

long vMServerAdr ; 

long vMVolumeGrade ; 



/♦version number*/ 
/*vol\ime attributes*/ 
/*reserved*/ 

/♦network server address*/ 
/♦relative speed rating*/ 



short 



vMForeignPrivID; /♦foreign privilege model*/ 



}; 



typedef struct GetVolParmsInf oBuffer GetVolParmsInf oBuffer; 



Volume Mounting Information Records 

struct VolMountInfoHeader{ 

short length; 
VolumeType media ; 

}; 



/*volume mounting information*/ 
/♦length of mounting inf ormation^/ 
/♦type of volume^/ 



typedef struct VolMountlnfoHeader VolMountInf oHeader ; 
typedef VolMountlnfoHeader *VolMountInf oPtr; 



struct AFPVolMountInfo( 



short 

VolumeType 

short 

char 

char 

short 

short 

short 

short 

short 

short 

short 

char 



); 



lengths- 
media; 
flags; 

nbplnterval; 
nbpCount ; 
uamType ; 
zoneNameOf f set ; 
serverNameOf f set ; 
volNameOf f set ; 
userNameOf f set ; 
userPasswordOf f set ; 
volPasswordOf f set ; 
AFPData(144] ; 



/*AFP volume mounting information*/ 

/* length of mounting information*/ 

/♦type of volume*/ 

/♦reserved; must be set to ©♦/ 

/♦NBP retry interval^/ 

/♦NBP retry count*/ 

/♦user authentication method^/ 

/♦offset to zone name*/ 

/♦offset server name*/ 

/♦offset to volume name*/ 

/♦offset to user name*/ 

/♦offset to user password^/ 

/♦offset to volume password^/ 

/♦standard AFP mounting into*/ 



typedef struct AFPVolMountInf o AFPVolMountInf o; 
typedef AFPVolMountlnfo ♦AFPVolMountlnfoPtr; 
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Internal Data Types 



Volume and File Control Blocks 



struct VCB { 




/*voluitie control block*/ 


QElemPtr 


qLink; 


/*next queue entry*/ 


short 


qType ; 


/*queue type*/ 


short 


vcbFlags; 


/*voluine flags (bit 15 = 1 if dirty)*/ 


unsigned short 


vcbSigWord; 


/*volume signature*/ 


unsigned long 


vcbCrDate; 


/*date and. time of volume creation*/ 


iinsicmed lonq 


vcbLsMod; 


/*date and time of last modification*/ 


short 


vcbAtrb; 


/*volume attributes*/ 


unsigned short 


vcbNmFls; 


/*number of files in root directory*/ 


short 


vcbVBMSt ; 


/*first block of voliime bitmap*/ 


short 


vcbAllocPtr ; 


/* start of next allocation search*/ 


nnciianed short 


vcbNmAlBlks ; 


/*number of allocation blocks in */ 






/* volume*/ 


J. ong 


vcbAlBlkSiz ; 


/*size (in bytes) of allocation */ 






/* blocks*/ 


j.ong 


vcbClpSiz ; 


/*default clump size*/ 


short 


vcbAlBlSt ; 


/*first allocation block in volume*/ 


long 


vcbNxtCNID : 


/*next unused catalog node ID*/ 


unci "i nrkpd *5hort 


vcbFreeBks ; 


/*number of unused allocation blocks*/ 


Str27 


vcbVN? 


/* volume name*/ 


short 


vcbDrvNuin ; 


/* drive number*/ 


short 


vcbDRe f Num ; 


/*driver reference number*/ 


short 


vrbFSID- 


/*f ile-system identifier*/ 


short 


vcbVRe f Num ; 


/*volume reference number*/ 


Pt-T 
r V- J. 


vcbMAdr ; 


/*used internally*/ 


PI- T 

XT L.X. 


vcbBuf Adr ; 


/*used internally*/ 


short 


vcbMLen; 


/*used internally*/ 


short 


vcbDir Index; 


/*used internally*/ 


short 


vcbDirBlk; 


/*used internally*/ 


unsigned long 


vcbVolBkUp; 


/*date and time of last backup*/ 


unsigned short 


vcbVSeqNum; 


/*volume backup sequence niimber*/ 


long 


vcbWrCnt ; 


/* volume write count*/ 


long 


vcbXTClpSiz; 


/* clump size for extents overflow */ 






/* file*/ 


long 


vcbCTClpSiz; 


/*clump size for catalog file*/ 


unsigned short 


vcbNmRtDirs; 


/♦number of directories in root dir.*/ 


long 


vcbFilCnt; 


/*number of files in volxime*/ 


long 


vcbDirCnt; 


/*number of directories in volxame*/ 



long 



vcbFndrInfo[8] ; /*information used by the Finder*/ 
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unsigned short 
unsigned short 
unsigned short 
unsigned short 
unsigned short 
short 

short 
Ptr 
long 
short 



vcbVCSize; 

vcbVBMCSiz; 

vcbCtlCSiz; 

vcbXTAlBlks; 

vcbCTAlBlks; 

vcbXTRef ; 

vcbCTRef ; 
vcbCtlBuf ; 
vcbDirlDM; 
vcbOf fsM; 



}; 



typedef struct VCB VCB; 
struct FCB { 



long 


f cbFlNum; 


short 


fcbFlags; 


short 


fcbSBlk; 


long 


fcbEOF; 


long 


f cbPLen ; 


long 


f cbCrPs; 


Ptr 


fcbVPtr; 


Ptr 


fcbBfAdr; 


short 


f cbFlPos; 


long 


f cbClmpSize; 


Ptr 


fcbBTCBPtr; 


ExtDataRec 


f cbExtRec; 


long 


fcbFType; 


long 


f cbCatPos; 


long 


fcbDirlD; 


Str31 


f cbCName; 



); 



typedef struct FCB FCB; 



/*used internally*/ 

/*used internally*/ 

/*used internally*/ 

/*size of extents overflow file*/ 

/*size of catalog file*/ 

/*ref. num. for extents overflow */ 

/* file*/ 

/*ref. num. for catalog file*/ 

/*ptr. to extents and catalog caches*/ 

/♦directory last searched*/ 

/*off spring index at last search*/ 



/*file control block*/ 
/*file ID*/ 
/*file flags*/ 

/*first allocation block of file*/ 
/*logical end-of-f ile*/ 
/*physical end-of-f ile*/ 
/♦current file mark position*/ 
/*pointer to volume control block*/ 
/♦pointer to access path buffer*/ 
/*unused*/ 
/♦file clump size*/ 

/♦pointer to B^-tree control block*/ 
/*first three file extents*/ 
/*file's four Finder type bytes*/ 
/♦catalog hint for use on Close^/ 
/♦file's parent directory ID^/ 
/♦name of file*/ 



Drive Queue Elements 



struct DrvQEl 
QElemPtr 
short 
short 
short 
short 



{ 



/*drive queue element*/ 
qLink; /*next queue entry*/ 

qType; /*flag for dQDrvSz and dQDrvSz2*/ 

dQDrive; /* drive number*/ 

dQRefNum; /*driver reference number*/ 

dQFSID; /*f ile-system identifier*/ 
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.;unsigned short dQDrvSz; 
-unsigned short dQDrvSz2; 



typedef struct DrvQEl DrvQEl? 



/*nuinber of logical blocks on drive*/ 
/^additional field for large drives*/ 



High-level File Access Routines 



Reading, Writing, and Closing Files 



pascal OSErr FSRead 
pascal OSErr FSWrite 
pascal OSErr FSClose 

Manipulating the File Mark 

pascal OSErr GetFPos 
pascal OSErr SetFPos 

Manipulating the Fnd-of-File 

pascal OSErr GetEOF 
pascal OSErr SetEOF 

Allocating File Blocks 

pascal OSErr Allocate 
pascal OSErr AllocContig 



(short refNum, long *count, Ptr buf fPtr) ; 
(short refNum, long *count, Ptr buf fPtr) ; 
(short refNum) ; 



(short refNum, long *f ilePos) ; 

(short refNum, short posMode, long posOff ) ; 



(short refNum, long *logEOF); 
(short refNum, long logEOF) ; 



(short refNum, long * count ) ; 
(short refNum, long * count ) ; 



Low-Level File Access Routines 



Reading, Writing, and Closing 

pascal OSErr PBRead 
pascal OSErr PBReadSync 
pascal OSErr PBReadAsync 
pascal OSErr PBWrite 
pascal OSErr PBWriteSync 
pascal OSErr PBWriteAsync 
pascal OSErr PBClose 
pascal OSErr PBCloseSync 
pascal OSErr PBCloseAsync 



Files 

(ParmBlkPtr 
(ParmBlkPtr 
(ParmBlkPtr 
(ParmBlkPtr 
(ParmBlkPtr 
(ParmBlkPtr 
(ParmBlkPtr 
(ParmBlkPtr 
(ParmBlkPtr 



paramBlock, Boolean async) ; 
pareimBlock) ; 
paramBlock) ; 

paramBlock, Boolean async); 
paramBlock) ; 
paramBlock) ; 

paramBlock, Boolean async) ; 
paramBlock) ; 
paramBlock) ; 
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Manipulating the File Mark 

pascal OSErr PBGetFPos 
pascal OSErr PBGetFPosSync 
pascal OSErr PBGetFPosAsync 
pascal OSErr PBSetFPos 
pascal OSErr PBSetFPosSync 



(ParmBlkPtr paramBlock, Boolean asyrlc) ; 

(ParmBlkPtr paramBlock) ; 

(ParmBlkPtr paramBlock); 

(ParmBlkPtr paramBlock, Boolean async) ; 

(ParmBlkPtr paramBlock); 



pascal OSErr PBSetFPosAsync (ParmBlkPtr paramBlock); 



Manipulating the End-of-File 

pascal OSErr PBGetEOF 
pascal OSErr PBGetEOFSync 
pascal OSErr PBGetEOFAsync 
pascal OSErr PBSetEOF 
pascal OSErr PBSetEOFSync 
pascal OSErr PBSetEOFAsync 



(ParmBlkPtr paramBlock, Boolean async); 

(ParmBlkPtr paramBlock); 

(ParmBlkPtr paramBlock) ; 

(ParmBlkPtr paramBlock, Boolean async) ; 

(ParmBlkPtr paramBlock) ; 

(ParmBlkPtr paramBlock); 



Allocating File Blocks 

pascal OSErr PBAllocate (ParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBAllocateSync (ParmBlkPtr paramBlock) ; 

pascal OSErr PBA ll oca teA sync (ParmBlkPtr paramBlock); 

pascal OSErr PBAllocContig (ParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBAllocContigSync 

(ParmBlkPtr paramBlock); 

pascal OSErr PBAllocContigAsync 

(ParmBlkPtr paramBlock) ; 

Updating Files 

pascal OSErr PBFlushFile (ParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBFlushFileSync (ParmBlkPtr paramBlock); 

pascal OSErr PBFlushFileAsync 

(ParmBlkPtr paramBlock); 



Higlt-Level Volume Access Routines 

Umnounting Volumes 

pascal OSErr UnmountVol (StringPtr volName, short vRefNum) ; 

pascal OSErr Eject (StringPtr yolName, short vRefNum) ; 
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Updating Volumes 

pascai OSErr FlushVol (StringPtr volName, short vRefNum) ; 

Manipulating the Default Volume 

pascal OSErr GetVol (StringPtr volName, short *vRefNuin) ; 

pascal OSErr SetVol (StringPtr volName, short vRefNum) ; 

pascal OSErr HGetVol (StringPtr volName, short *vRefNum, 

long *dirID) ; 

pascal OSErr HSetVol (StringPtr volName, short vRefNum, long dirlD) 

Obtaining Volume Information 

pascal OSErr GetVInfo (short drvNnm, StringPtr volName, 

short *vRefNuin, long *freeBytes) ; 

pascal OSErr GetVRefNum (short refNum, short *vRefNum) ; 

Low-Level Volume Access Routines 

Mounting and Unmounting Volumes 

pascal OSErr PBMountVol (ParmBlkPtr paramBlock) ; 

pascal OSErr PBUnmountVol (ParmBlkPtr paramBlock); 
pascal OSErr PBEject (ParmBlkPtr paramBlock); 

pascal OSErr PBOffLine (ParmBlkPtr paramBlock); 

Updating Volumes 

pascal OSErr PBFlushVol (ParmBlkPtr paramBlock; Boolean async) ; 

pascal OSErr PBFlushVol Sync (ParmBlkPtr paramBlock); 
pascal OSErr PBFlushVolAsync (ParmBlkPtr paramBlock) ; 

Obtaining Volume Information 

pascal OSErr PBHGetVInfo (HPannBlkPtr paramBlock, Boolean async); 

pascal OSErr PBHGetVInf oSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHGetVInfoAsync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBSetVInfo (HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBSetVInfoSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBSetVInfoAsync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHGetVolParms (HParmBlkPtr paramBlock, Boolean async) ; 
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pascal OSErr PBHGetVolParmsSync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHGetVolParmsAsync 

(HParmBlkPtr paramBlock) ; 



Manipulating the Default Volume 

pascal OSErr PBGetVol 
pascal OSErr PBGetVolSync 
pascal OSErr PBGetVolAsync 
pascal OSErr PBSetVol 
pascal OSErr PBSetVolSync 
pascal OSErr PBSetVolAsync 
pascal OSErr PBHGetVol 
pascal OSErr PBHGetVolSync 



(ParmBlkPtr paramBlock, Boolean async) ; 
(ParmBlkPtr paramBlock); 
(ParmBlkPtr paramBlock); 
(ParmBlkPtr paramBlock, Boolean async); 
(ParmBlkPtr paramBlock); 
(ParmBlkPtr paramBlock) ; 
(WDPBPtr paramBlock, Boolean async) ; 



(WDPBPtr paramBlock) ; 
pascal OSErr PBHGetVol A sync (WDPBPtr paramBlock) ; 
pascal OSErr PBHSetVol (WDPBPtr paramBlock, Boolean async); 

pascal OSErr PBHSetVolSync (WDPBPtr paramBlock) ; 
pascal OSErr PBHSetVol Async (WDPBPtr paramBlock) ; 



File System Specification Routines 



Opening Files 

pascal OSErr FSpOpenDF 

pascal OSErr FSpOpenRF 



(const FSSpec *spec, char permission, 
short *refNum) ; 

(const FSSpec *spec, char permission, 
short *refN\im) ; 



Creating and Deleting Files and Directories 

pascal OSErr FSpCreate (const FSSpec *spec, OSType creator, 

OSType fileType, ScriptCode scriptTag) ; 

pascal OSErr FSpDirCreate (const FSSpec *spec, ScriptCode scriptTag, 

long *createdDirID) ; 

pascal OSErr FSpDelete (const FSSpec *spec) ; 



Accessing Information About Files and Directories 

pascal OSErr FSpGetFInfo (const FSSpec *spec 
pascal OSErr FSpSetFInfo 
pascal OSErr FSpSetFLock 
pascal OSErr FSpRstFLock 
pascal OSErr FSpRename 



FInfo *fndrInfo) ; 
(const FSSpec *spec, const FInfo *fndrInfo) ; 
(const FSSpec *spec) ; 
(const FSSpec *spec) ; 

(const FSSpec *spec, ConstStr255Param newName) ; 



Summary of the File Manager 



2-283 



TIVO-408733 



CHAPTER 2 

File Manager 

*"> — 

Moving Files or Directories 

pascal' OSErr FSpCatMove (const FSSpec ^source, const FSSpec *dest) ; 

Exchanging the Data in Two Files 

pascal OSErr FSpExchangeFiles 

(const FSSpec *source, const FSSpec *dest) ; 

Creating File System Specifications 

pascal OSErr FSMakeFSSpec (short vRefNiim/ long dirlD, 

ConstStr255Param fileName, FSSpecPtr spec) 

pascal OSErr PBMakeFSSpec (HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBMakeFSSpecSync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBMakeFSSpecAsync 

(HParmBlkPtr paramBlock) ; 

High-level HFS Routines 

Opening Files 

pascal OSErr HOpenDF (short vRefNum, long dirlD, 

const Str255 fileName, char permission, 
short *refNum) ; 

pascal OSErr HOpenRF (short vRefNxam, long dirlD, 

const Str255 fileName, char permission, 
short *refNum) ; 

pascal OSErr HOpen (short vRefNum, long dirlD, 

const Str255 fileName, char permission, 
short *refNum) ; 

Creating and Deleting Files and Directories 

pascal OSErr HCreate (short vRefNum, long dirlD, 

const Str255 fileName, OSType creator, 
OSType f ileType) ; 

pascal OSErr DirCreate (short vRefNum, long parentDirlD, 

const Str255 directoryName, 
long *createdDirID) ; 

pascal OSErr HDelete (short vRefKum, long dirlD, 

const Str255 fileName); 
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Accessing Infonnation About Files and Directories 

pascal OSErr HGetFInfo 

pascal OSErr HSetFInfo 
pascal OSErr HSetFLock 
pascal OSErr HRstFLock 
pascal OSErr HRename 

Moving Files or Directories 

pascal OSErr CatMove 

Maintaining Working Directories 

pascal OSErr OpenWD (short vRefNum, long dirlD, long procID, 

short *wdRefNuin) ; 

pascal OSErr CloseWD (short wdRefNum) ; 

pascal OSErr GetWDInfo (short wdRefNum, short *vRefNum, long *dirID, 

long *procID) ; 



I 



(short vRefNum, long dirlD, 
const Str255 fileName, FInfo *fndrInfo) ; 

(short vRefNum, long dirlD, 

const Str255 fileName, const FInfo *fndrInfo); 

(short vRefNum, long dirlD, 
const Str255 fileName) ; 

(short VRefNum, long dirlD, 
const Str255 fileName) ; 

(short vRefNum, long dirlD, ® 
const Str255 oldName, const Str255 newName) ; w 

IB 
(Q 
(D 
—1 

(short VRefNum, long dirlD, 
const Str255 oldName, long newDirlD, 
const Str255 newName) ; 



-n 



Low-Level HFS Routines 



Opening Files 

pascal OSErr 
pascal OSErr 
pascal OSErr 
pascal OSErr 
pascal OSErr 
pascal OSErr 
pascal OSErr 
pascal OSErr 
pascal OSErr 



PBHOpenDF 

PBHOpenDFSync 

PBHOpenDFAsync 

PBHOpenRF 

PBHOpenRFSync 

PBHOpenRFAsync 

PBHOpen 

PBHOpenSync 

PBHOpenAsync 



(HParmBlkPtr paramBlock, Boolean async) ; 

(HParmBlkPtr paramBlock) ; 

(HParmBlkPtr paramBlock) ; 

(HParmBlkPtr paramBlock, Boolean async); 

(HParmBlkPtr paramBlock) ; 

(HParmBlkPtr paramBlock) ; 

(HPaimBlkPtr paramBlock, Boolean async) 

(HParmBlkPtr paramBlock) ; 

(HParmBlkPtr paramBlock) ; 
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Creating and Deleting Files and Directories 

pascal -OSErr PBHCreate (HPanuBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBHCreateSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHCreateAsync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBDirCreate (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBDirCreateSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBDirCreateAsync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHDelete (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBHDeleteSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHDeleteAsync (HParmBlkPtr paramBlock) ; 

Accessing Information About Files and Directories 

pascal OSErr PBGetCatlnfo (ClnfoPBPtr paramBlock, Boolean async); 

pascal OSErr PBGetCatInf oSync 

(ClnfoPBPtr paramBlock, Boolean async); 

pascal OSErr PBGetCatInf oAsync , • 

(ClnfoPBPtr paramBlock) ; 

pascal OSErr PBSetCatlnfo (ClnfoPBPtr paramBlock, Boolean async); 

pascal OSErr PBSetCatInf oSync 

^' (ClnfoPBPtr paramBlock) ; 

pascal OSErr PBSetCatInf oAsync 

(ClnfoPBPtr paramBlock) ; 

pascal OSErr PBHGetFInfo (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBHGetFInf oSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHGetFInf oAsync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHSetFInf o (HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBHSetFInf oSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHSetFInf oAsync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHSetFLock (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBHSetFLockSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHSetFLockAsync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHRstFLock (HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBHRstFLockSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHRstFLockAsync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHRename (HParmBlkPtr paramBlock, Boolean async) ; 
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pascal OSErr PBHRenameSync (HParmBlkPtr paramBlock) ; 
pascal OSErr PBHRenameAsync (HParmBlkPtr paramBlock) ; 

Moving Files or Directories 

pascal OSErr PBCatMove (CMovePBPtr paramBlock, Boolean async) ; 

pascal OSErr PBCatMoveSync (CMovePBPtr paramBlock) ; 

pascal OSErr PBCatMoveAsync (CMovePBPtr paramBlock) ; 

Maintaining Working Directories 

pascal OSErr PBOpenWD (WDPBPtr paramBlock, Boolean async) ; 

pascal OSErr PBOpenWDSync (WDPBPtr paramBlock) ; 

pascal OSErr PBOpenWDAsync (WDPBPtr paramBlock) ; 

pascal OSErr PBCloseWD (WDPBPtr paramBlock, Boolean async); 

pascal OSErr PBCloseWDSync (WDPBPtr paramBlock) ; 

pascal OSErr PBCloseWDAsync (WDPBPtr paramBlock) ; 

pascal OSErr PBGetWDInfo (WDPBPtr paramBlock, Boolean async) ; 

pascal OSErr PBGetWDInfoSync (WDPBPtr paramBlock); 

pascal OSErr PBGetWDInf oAsync 

(WDPBPtr paramBlock) ; 

Searching a Catalog 

pascal OSErr PBCatSearch (HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBCatSearchSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBCatSearchAsync 

(HParmBlkPtr paramBlock) ; 

Exchanging the Data in Two Files 

pascal OSErr PBExchangeFiles (HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBExchangeFilesSync 

(HParmBlkPtr paramBlock) ; 

ipascal OSErr PBExchangeFilesAsync 

(HParmBlkPtr paramBlock) ; 

Shared Environment Routines 

Opening Files While Denying Access 

pascal OSErr PBHOpenDeny (HParmBlkPtr paramBlock, Boolean async) ; 
pascal OSErr PBHOpenDenySync (HParmBlkPtr paramBlock) ? 
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pascal; OSErr PBHOpenDenyAsync 

; (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHOpenRFDeny (HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBHOpenRFDeny Sync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHOpenRFDenyAsync 

(HParmBlkPtr paramBlock) ; 

Locking and Unlocking File Ranges 

pascal OSErr PBLockRange (ParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBLockRange Sync (ParmBlkPtr paramBlock); 

pascal OSErr PBLockRangeAsync 

(ParmBlkPtr paramBlock) ; 

pascal OSErr PBUnlockRange (ParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBUnlockRangeSync 

(ParmBlkPtr paramBlock); 

pascal OSErr PBUnlockRangeAsync 

(ParmBlkPtr paramBlock); 

Manipulating Share Points 

pascal OSErr PBShare (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBShareSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBShareAsync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBUnshare (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBUnshaireSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBUnshareAsync (HParmBlkPtr paramBlock); 

pascal OSErr PBGetUGEntry (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBGetUGEntrySync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBGetUGEntry Async 

(HParmBlkPtr paramBlock) ; 

Controlling Directory Access 

pascal OSErr PBttGetDir Access (HParmBlkPtr paramBlock, Boolean async) 

pascal OSErr PBHGetDirAccessSync 

(HParmBlkPtr paramBlock); 

pascal OSErr PBHGetDirAccessAsync 

(HParmBlkPtr paramBlock) ; 



2-288 Summary of the File Manager 



CHAPTER 2 



pie Manager 

pascal OSErr PBHSetDirAccess (HParmBlkPtr paramBlock, Boolean async) ; 
pascal OSErr PBHSetDirAccessSync 

(HParmBlkPtr paramBlock) ; 
pascal OSErr PBHSetDirAccessAsync 

(HParmBlkPtr paramBlock) ; 

Mounting Volumes 

pascal OSErr PBGetVolMountInf oSize 

(F 

pascal OSErr PBGetVolMountInf o 



(ParmBlkPtr paramBlock); _^ 



(ParmBlkPtr paramBlock); » 
pascal OSErr PBVolumeMount (ParmBlkPtr paramBlock) ; «g 

Controlling Login Access 

pascal OSErr PBHGetLoglnlnfo (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBHGetLoglnInf oSync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHGetLoglnlnfoAsync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHMapID (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBHMapIDSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHMapIDAsync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHMapName (HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBHMapNameSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHMapNameAsync (HParmBlkPtr paramBlock) ; 

Copying and Moving Files 

pascal OSErr PBHCopyFile (HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBHCopyFileSync (HParmBlkPtr paramBlock) ; 

pascal OSErr PBHCopyFileAsync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBHMoveRename (HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBHMoveRename Sync 

(HParmBlkPtr paramBlock); 

pascal OSErr PBHMpveRenameAsync 

(HParmBlkPtr paramBlock) ; 
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File ID Routines 



Resolviftg File ID References 

pascal OSErr PBResolveFilelDRef 

(HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBResolveFilelDRef Sync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBResolveFilelDRef Async 

(HParmBlkPtr paramBlock) ; 

Creating and Deleting File ID References 

pascal OSErr PBCreateFilelDRef 

(HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBCreateFilelDRef Sync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBCreateFilelDRef Async 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBDeleteFilelDRe'f 

(HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBDeleteFilelDRef Sync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBDeleteFilelDRef Async 

(HParmBlkPtr paramBlock) ; 



Foreign File System Routines 



Accessing Privilege Information in Foreign File Systems 

pascal OSErr PBGetForeignPrivs 

(HParmBlkPtr paramBlock, Boolean async) ; 

pascal OSErr PBGetForeignPrivsSync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBGetForeignPrivsAsync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBSetForeignPrivs 

(HParmBlkPtr paramBlock, Boolean async); 

pascal OSErr PBSetForeignPrivsSync 

(HParmBlkPtr paramBlock) ; 

pascal OSErr PBSetForeignPrivsAsync 

(HParmBlkPtr paramBlock) ; 
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Utility Routines 



Obtaining Queue Headers 

^define GetFSQHdr( ) (QHdrPtr) ; 

tdefine GetVCBQHdrO (QHdrPtr); 

#define GetDrvQHdrO (QHdrPtr); 

Adding a Drive 

pascal void AddDrive (short drvrRefNum, short drvNum, DrvQElPtr qEl); 



I 



Obtaining File Control Block Information S 

pascal OSErr PBGetFCBInfb (FCBPBPtr paramBlock, Boolean async) ; 
pascal OSErr PBGetFCBInf oSync 

(FCBPBPtr paramBlock) ; 
pascal OSErr PBGetFCBInf oAsync 

(FCBPBPtr paramBlock); 

Application-Defined Routine ^ 



Completion Routines 

pascal void MyCompletionProc (void) ; 

Assembly-Language Summary 



Constants 



; flags in trap words 

MsBit EQU 9 .;set for an HFS call 

asyncTrpBit EQU 10 ;set for an asynchronous call 

;masks for flags in trap words 

newHFS EQU $200 ;make an HFS call 

ASYNC EQU $400 ;make an asynchronous call 
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Data Structures 



File System Specification Record 



0 


vRefNum 


word 


volume reference number 


2 


parlD 


long 


parent directory ID 


6 


name 


64 bytes 


jfilename or directory name 


HFS 


Parameter Block Common Fields 




0 


qLink 


long 


next queue entry 


4 


qType 


word 


queue type 


6 


ioTrap 


word 


routine trap 


8 


ioCmdAddr 


long 


routine address 


12 


ioCompletion 


long 


address of completion routine 


16 


ioResult 


word 


result code 


18 


ioNamePtr 


long 


pointer to pathname 


22 


ioVRefNum 


word 


volume specification 



I/O Parameter Variant 

24 ioRefNum word 

26 ioVersNum byte 

27 ioPermssn byte 

28 ioMisc long 
32 ioBuffer long 
36 ioReqCount long 
40 ioActCount long 
44 ioPosMode word 
46 ioPosOffset long 

File Parameter Variant 

24 ioFRefNum word 

26 ioFVersNum byte 

27 fillerl byte 

28 ioFDirlndex word 

30 ioFlAttrib byte 

31 ioFlVersNum byte 

32 ioFlFndrlnfo 16 bytes 
48 ioDirlD long 

52 ioFlStBlk word 

54 ioFlLgLen long 

58 ioFlPyLen long 

62 ioFlRStBlk word 
64 ioFlRLgLen long 
68 ioFlRPyLen long 
72 ioFlCrDat long 
76 ioFlMdDat long 



file reference number 
version number 
read /write permission 
nuscellaneous 
data buffer 

requested number of bytes 

actual number of bytes 

positioning mode and newline character 

positioning offset 



file reference number 

file version number (unused) 

reserved 

directory index 

file attributes 

file version number (unused) 

information used by the Finder 

directory ID or file ID 

first allocation block of data fork 

logical end-of-file of data fork 

physical end-of-file of data fork 

first allocation block of resoim:e fork 

logical end-of-file of resource fork 

physical end-of-file of resource fork 

date and time of creation 

date and time of last modification 
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Volume Parameter Variant 



24 


. f iller2 


long 


28 


ioVolIndex 


word 


30 


ioVCrDate 


lone 


34 


ioVLsMod 


lone 


38 


ioVAtrb 


word 


40 


ioVNmFls 


word 


42 


ioVBitMap 


word 


44 


ioAllocPtr 


word 


46 


ioVNitiAlBlks 


word 


48 


ioVAlBlkSi2 


lone 


50 


ioVClpSiz 


long 


54 


ioAlBlSt 


word 


56 


ioVNxtCNID 


lone 


60 


ioVFrBlk 


word 


62 


ioVSigWord 


word 


64 


ioVDrvInf o 


word 


66 


ioVDRefNum 


word 


68 


ioVFSID 


word 


70 


ioVBkUp 


long 


74 


ioVSeqNum 


word 


76 


ioVWrCnt 


long 


80 


ioVFilCnt 


long 


84 


ioVDirCnt 


long 


88 


ioVFndrInf o 


32 bytes 


Access Variant 




24 


fillers 


word 


26 


ioDenyModes 


word 


28 


filler4 


word 


30 


fillers 


byte 


31 


ioACUser 


byte 


32 


fillers 


long 


36 


ioACOwnerlD 


long 


40 


ioACGroupID 


long 


44 


ioACAccess 


long 


Object Variant 




24 


fillerV 


word 


26 


ioObjType 


word 


28 


ioObjNamePtr 


long 


32 


ioObjID 


long 


Copy Variant 




24 


ioDstVRefNum 


word 


26 


fillers 


word 


28 


ioNewName 


long 


32 


ioCopyName 


long 


36 


ioNewDirlD 


long 



reserved 
volume index 

date and time of initialization 

date and time of last modification 

volume attributes 

number of files in root directory 

first block of volume bitmap 

first block of next new file 

number of allocation blocks 

size of allocation blocks 

default clump size 

first block in volume map 

next imused node ID 

number of unused allocation blocks 

volume signature 

drive number 

driver reference number 

file-system identifier 

date and time of last backup 

used internally 

volume write coimt 

number of files on volume 

number of directories on volume 

information used by the Finder 



reserved 

access mode information 

reserved 

reserved 

user access rights 
reserved 
owner ID 
group ID 

directory access rights 



reserved 
fimction code 

pointer to returned creator/ group name 
creator/ group ID 



destination volume identifier 
reserved 

pointer to destination pathname 

pointer to optional name 

directory ID of destination directory 
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Working Directory Variant 



24 
26 
28 
32 
34 
36 
40 
44 
48 



fillers 

ioWDIndex 

ioWDProcID 

ioWDVRefNum 

f illerlO 

fillerll 

fillerl2 

fillerl3 

ioWDDirlD 



word reserved 

word working directory's index 

long working directory's user identifier 

word working directory's volume reference number 

word reserved 

long reserved 

long reserved 

long reserved 

long working directory's directory ID 



File ID Variant 

24 filler 14 long 

28 ioDestNamePtr long 

32 fillerl5 long 

36 ioDestDirlD long 

40 fillerl6 long 

44 fillerl7 long 

48 ioSrcDirlD long 

52 fillerlS word 

54 ioFilelD • " long 



reserved 

pointer to destination filename 
reserved 

destination parent directory ID 

reserved 

reserved 

source parent directory ID 

reserved 

file ID 



Catalog Search Variant 



24 


ioMatchPtr 


long 


28 


ioReqMatchCount 


long 


32 


ioActMatchCount 


long 


36 


ioSearchBits 


long 


40 


ioSearchInf ol 


long 


44 


ioSearchInfo2 


long 


48 


ioSearchTime 


long 


52 


ioCatPosition 


16 bytes 


68 


ioOptBuf fer 


long 


72 


ioOptBufSize 


long 



pointer to array of matches 

maximum match count 

actual match count 

search criteria selector 

pointer to values and lower boimds 

pointer to masks and upper boimds 

time limit on search 

catalog position record 

pointer to optional read buffer 

length of optional read buffer 



Foreign Privileges Variant 



24 


filler21 


long 


28 


filler22 


long 


32 


ioForeignPrivBuf f er 


long 


36 


ioForeignPrivReqCount 


long 


40 


ioForeignPrivActCount 


long 


44 


filler23 


long 


48 


ioForeignPrivDirlD 


long 


52 


ioForeignPrivInfol 


long 


56 


ioForeignPrivInfo2 


long 


60 


ioForeignPrivInfoB 


long 


64 


ioForeignPrivInfo4 


long 



reserved 
reserved 

pointer to privileges data buffer 
size allocated for buffer 
amoimt of buffer used 
reserved 

parent directory ID of target 
privileges data 
privileges data 
privileges data 
privileges data 
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Catalog Information Parameter Block (Files Variant) 



24 


ioFRefNum 


word 


file reference number 


26 


ioFVersNum 


byte 


version number 


27 


fillerl 


byte 


reserved 


28 


ioFDirlndex 


word 


directory index 


30 


ioFlAttrib 


byte 


file attributes 


31 


ioACUser 


byte 


directory access rights 


32 


ioFlUsrWds 


16 bytes 


information used by the Finder 


48 


ioFlNum 


long 


file ID 


52 


ioFlStBlk 


word 


first allocation block of data fork 


54 


ioFlLgLen 


long 


logical end-of-file of data fork 


58 


ioFlPyLen 


long 


physical end-of-file of data fork 


62 


ioFlRStBlk 


word 


first allocation block of resource fork 


64 


ioFlRLgLen 


long 


logical end-of-file of resource fork 


68 


ioFlRPyLen 


long 


physical end-of-file of resource fork 


72 


ioFlCrDat 


long 


date and time of creation 


76 


ioFlMdDat 


long 


date and time of last modification 


80 


ioFlBkDat 


long 


date and time of last backup 


84 


ioFlXFndrInf o 


16 bytes 


additional information used by the Finder 


100 


ioFlParlD 


long 


file parent directory ID 


104 


ioFlClpSiz 


long 


file's clump size 


Catalog Information Parameter Block (Directories Variant) 


24 


ioFRefNum 


word 


file reference number 


26 


ioFVersNiim 


byte 


version nimiber 


27 


fillerl 


byte 


reserved 


28 


ioFDirlndex 


word 


directory index 


30 


ioFlAttrib 


byte 


directory attributes 


31 


ioACUser 


byte 


directory access rights 


32 


ioDrUsrWds 


16 bytes 


information used by the Finder 


48 


ioDrDirlD 


long 


directory ID 


52 


ioDrNmFls 


word 


number of files in directory 


54 


fillers 


18 bytes 


reserved 


72 


ioDrCrDat 


long 


date and time of creation 


76 


ioDrMdDat 


long 


date and time of last modification 


80 


ioDrBkDat 


long 


date and time of last backup 


84 


ioDrFndrInf o 


16 bytes 


additional information used by the Finder 


100 


ioDrParlD 


long 


directory's parent directory ID 


Catalog Position Record 






0 


initialize 


long 


starting place for next search 


4 


priv 


12 bytes 


private data 
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Catalog Move Parameter Block 



24 


fillerl 


long 


28 


ioNewName 


long 


32 


filler^ 


long 


36 


ioNewDirlD 


long 


40 


fillers 


8 bytes 


48 


ioDirlD 




Working Directory Parameter 


Block 


24 


fillerl 


word 




io WD Index 


word 


28 


ioWDProcID 

JL V_/ fH J- J- V-/ w -L- J-* 


long 


32 


ioWDVRefNum 


word 


34 


filler2 


14 byte 


48 


ioWDDirlD 


long 


File 


Control Block Parameter 


111 

iSiOCK 


24 


ioRefNum 


word 


26 


filler 


word 


28 


ioFCBIndx 


word 


30 


ioFCBfillerl 


word 


32 


ipFCBFlNm 


long 


36 


ioFCBFlags 


word 


38 


ioFCBStBlk 


word 


40 


ioFCBEOF 


long 


44 


ioFCBPLen 


long 


48 


ioFCBCrPs 


long 


52 


ioFCBVRefNum 


word 


54 


ioFCBClpSiz 


long 


58 


ioFCBParlD 


long 



Volume Attributes Buffer 



0 


vMVersion 


word 


2 


vMAttrib 


long 


6 


vMLocalHand 


long 


10 


vMServerAdr 


long 


14 


vMVolximeGrade 


long 


18 


vMForeignPrivID 


word 



Volume Mounting Information Record 

0 length word 
2 media 4 bytes 



reserved 

pointer to name of new directory 
reserved 

directory ID of new directory 
reserved 

directory ID of current directory 



reserved 

working directory's index 

working directory's user identifier 

working directory's volume reference number 

reserved 

working directory's directory ID 



file reference number 

reserved 

FCB index 

reserved 

file ID 

flags 

first allocation block of file 
logical end-of-file 
physical end-of-file 
position of the file mark 
volume reference number 
file's clump size 
parent directory ID 



version ntunber 
volume attributes 
reserved 

network server address 
relative speed rating 
foreign privilege model 



length of record 
type of volume 
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AFP Mounting Information Record 



0 


length 


word 


length of record 


2 


media 


4 bytes 


type of volume 


6 


flags 


word 


reserved; must be 0 


8 


nbplnterval 


byte 


NBP retry interval 


9 


nbpCount 


byte 


NBP retry count 


10 


uamType 


word 


user authentication method 


12 


zoneNameOf f set 


word 


offset to zone name 


14 


serverNameOf f set . 


word 


offset to server name 


16 


volNameOf f set 


word 


offset to volume name 


18 


userNameOf f set 


word 


offset to user name 


20 


userPasswordOf f set 


word 


offset to user password 


22 


volPasswordOf f set 


word 


offset to volume password 


24. 


AFPData 


144 bytes 


mounting data 



Volume Control Block Data Structure (Internal) 



0 


qLink 


lone 

o 


next queue entry 


4 


qType 


word 


queue type 


6 


vcbFlags 


word 


volume flags 


8 


vcbSigWord 


word 


volume signature 


10 


vcbCrDate- * 


long 


date and time of initialization 


14 


vcbLsMod 


long 


date and time of last modification 


18 


vcbAtrb 


word 


volume attributes 


20 


vcbNmFls 


word 


number of files in root directory 


22 


vcbVBMSt 


word 


first block of voliune bitmap 


24 


vcbAllocPtr 


word 


start of next allocation search 


26 


vcbNmAlBlks 


word 


number of allocation blocks in volume 


28 


vcbAlBlkSiz 


long 


size (in bytes) of allocation block 


32 


vcbClpSiz 


long 


default clump size 


36 


vcbAlBlSt 


word 


first allocation block in volume 


38 


vcbNxtCNID 


long 


next unused catalog node ID 


42 


vcbFreeBks 


word 


number of unused allocation blocks 


44 


vcbVN 


28 bytes 


volume name preceded by length byte 


72 


vcbDrvNum 


word 


drive number 


74 


vcbDRefNum 


word 


driver reference number 


76 


vcbFSID 


word 


file-system identifier 


78 


vcbVRefNum 


word 


volume reference number 


80 


vcbMAdr 


long 


pointer to block map 


84 


vcbBuf Adr 


long 


pointer to volume buffer 


88 


vcbMLen 


word 


number of bytes in block map 


90 


vcbDir Index 


word 


reserved 


92 


vcbDirBlk 


word 


reserved 


94 


vcbVolBkUp 


long 


date and time of last backup 


98 


vcbVSeqNum 


word 


volume backup sequence number 
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100 


\fcbWrCnt 


long 


104 


.vbbXTClpSiz 


long 


108 


vcbCTClpSiz 


long 


112 


vcbNmRtDirs 


word 


114 


vcbFilCnt 


long 


118 


vcbDirCnt 


long 


122 


vcbFndrlnfo 


32 bytes 


154 


vcbVCSize 


word 


156 


vcbVBMCSiz 


word 


158 


vcbCtlCSiz 


word 


160 


vcbXTAlBks 


word 


162 


vcbCTAlBks 


word 


164 


vcbXTRef 


word 


166 


vcbCTRef 


word 


168 


vcbCtlBuf 


long 


172 


vcbDirlDM 


long 


176 


vcbOffsM 


word 



volume write count 

clump size for extents overflow file 

clump size for catalog file 

number of directories in root directory 

number of files in volume 

number of directories in volume 

information used by the Finder 

reserved 

reserved 

reserved 

size in blocks of extents overflow file 

size in blocks of catalog file 

file reference number for extents overflow file 

file reference number for catalog file 

pointer to extents and catalog tree caches 

directory last searched 

offspring index at last search 



File 


Control Block Data Structure (Internal) 


0 


fcbFlNum 


long 


4 


f cbFlags 


word 


6 


fcbSBlk 


word 


8 


fcbEOF 


long 


12 


fcbPLen 


long 


16 


fcbCrPs 


long 


20 


fcbVPtr 


long 


24 


fcbBfAdr 


long 


28 


fcbFlPos 


word 


30 


fcbClmpSize 


long 


34 


fcbBTCBPtr 


long 


38 


fcbExtRec 


12 bytes 


50 


fcbFType 


long 


54 


fcbCatPos 


long 


58 


fcbDirlD 


long 


62 


f cbCName 


32 bytes 



file ID 
file flags 

first allocation block of file 

logical end-of-file 

physical end-of-file 

current file mark position 

pointer to volume control block 

pointer to access path buffer 

reserved 

file's clump size 

pointer to B*-tree control block 

first three file extents 

file's four Finder type bytes 

catalog hint for use on close 

file's parent directory ID 

name of open file, preceded by length byte 



Drive Queue Elements 



0 
4 
6 
8 

10 
12 
14 



qbink 

qType 

dQDrive 

dQRefNum 

dQFSID 

dQDrvSz 

dQDrvSz2 



long next queue entry 

word flag for dQDrvSz and dQDrvSz2 fields 

word drive nimiber 

word driver reference number 

word file-system identifier 

word number of logical blocks on drive 

word additional field for large drives 
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Trap Macros 



Trap Macro Names 

Pascal name 

PBAllocate 

PBAllocContig 

PBClose 

PBDirCreate 

PBEject 

PBFlushFile 

PBFlushVol 

PBGetEOF 

PBGetFPos 

PBGetVol , 

PBHCreate 

PBHDelete 

PBHGetFInfo 

PBHGetVInfo 

PBHGetVol 

PBHGetVolPa3nns 

PBHOpen 

PBHOpenRF 

PBHRename 

PBHRstFLock 

PBHSetFInfo 

PBHSetFLock 

PBHSetVol 

PBMountVol 

PBOffLine 

PBRead 

PBSetEOF 

PBSetFPos 

PBSetVInfo 

PBSetVol 

PBUnmountVol 

PBWrite 



Trap macro name 

_Allocate 

_AllocContig 

_Close 

_DirCreate 

_Eject 

_FlushFile 

_FlushVol 

_GetEOF 

_GetFPos 

_GetVol 

_HCreate 

_HDelete 

„HGetFileInfo 

_HGetVolInfo 

_HGetVol 

_GetVolParTns 

_HOpen 

_HOpenRF 

_HRename 

_HRstFLock 

„HSetFileInfo 

_HSetFLock 

_HSetVol 

_MountVol 

_0f fLine 

_Read 

_SetEOF 

_SetFPos 

_SetVolInfo 

_SetVol 

_UninountVol 

_Write 
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Trap Macros Requiring Routine Selectors 

_HFSDispatch 

Selector Routine 

$0001 PBOpenWD 

$0002 PBCloseWD 

$0005 PBCatMove 

$0006 PBDirCreate 

$0007 PBGetWDInfo 

$0008 PBGetFCBInfo 

$0009 PBGetCatlnfo 

$000A PBSetCatlnfo 

$000B PBSetVInfo 

$0010 PBLockRange 

$0011 PBUnlockRange 

$0014 PBC r ea teFilelDRef 

$0015 pBDeleteFilelDRef 

$0016 PBRe s o 1 veF i 1 e I DRe f 

$0017 PBExchangeF i 1 es 

$0018 PBCat Search 

$001A PBHOpenDF 

$001B PBMakeFSSpec 

$0030 PBHGetVolParins 

$0031 PBHGetLoglnlnfo 

$0032 PBHGetDirAccess 

$0033 PBHSetDirAccess 

$0034 PBHMapID 

$0035 PBHMapName 

$0036 PBHCopyFile 

$0037 PBHMoveRename 

$0038 PBHOpenDeny 

$0039 PBHOpenRFDeny 

$003F PBGet VolMount Inf oS i ze 

$0040 PBGetVolMountlnfo 

$0041 PBVolumeMount 

$0042 PBShare 

$0043 PBUnshare 
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Selector Routine 

$0044 PBGetUGEntry 

$0060 PBGetForeignPrivs 

$0061 PBSetForeignPrivs 

_HighLevelFSDispatch 

Selector Routine 

$0001 FSMakeFSSpec 

$0002 FSpOpenDF 

$0003 FSpOpenRF 

$0004 FSpCreate 

$0005 FSpDirCreate 

$0006 FSpDelete ; 

$0007 FSpGetFInfo 

$0008 FSpSetFInfo 

$0009 FSpSetFLock 

$000A FSpRstFLock 

$000B FSpRename 

$000C FSpCatMove 

$000D FSpOpenResFile 

$000E FSpCreateResFile 

$000F FSpExchangeFiles 

Global Variables 

Boot Dr i ve word Working directory reference number for startup volume. 

Def VCBPtr long Pointer to default volume control block. 

Dr^QHdr 10 bytes Drive queue header. 

FSFCBLen word Size of a file control block. 

FSQHdr 10 bytes File 1/ O queue header. 

ToExtFS long Pointer to external file system. 

VCBQHdr 10 bytes Volume control block queue header. 

Result Codes 

noErr 0 No error 

notOpenErr -28 AppleTalk is not open 

dirFulErr -33 File directory full 

dskFulErr -34 All allocation blocks on the volume are full 

nsvErr -35 Volume not found 

ioErr -36 I/O error 
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bdNamErr 

fnOpnErr 

eofErr 

posErr 

tmf oErr 

fnfErr 

wPrErr 

fLckdErr 

vLckdErr 

fBsyErr 

dupFNErr 
opWrErr 
paramErr 
rfNumErr 

gfpErr 

volOf flinErr 
permErr 
volOnLinErr 
nsDrvErr 

noMacDskErr 

extFSErr 

f sRnErr 

badMDBErr 

wrPermErr 

memFullErr 

dirNFErr 

tmwdoErr 

badMovErr 

wrgVolTypErr 

volGoneErr 

fsDSIntErr 

f idNotFoundErr 

f idExists 

notAFileErr 

dif fVolErr 

catChangedErr 

sameFileErr 
afpAccessDenied 

afpBadUAM 

a f pBadVer sNum 

a f pDeny Con f 1 i c t 



afpNoMoreLocks 
afpNoServer 



-37 Bad filename or volume name 

-38 File not open 

-39 Logical end-of-file reached 

-40 Attempt to position mark before start of file 

-42 Too many files open 

-43 File not found 

-44 Hardware volume lock 

-45 File is locked 

-46 Software volume lock 

-47 File is busy; one or more fUes are open; directory not 

empty or working directory control block is open 
-48 A file with the specified name already exists 
-49 File abready open for writing 
-50 Parameter error 

-51 Reference nxmiber specifies nonexistent access path; 

bad working directory reference number 
-52 Error during GetFPos 
-53 Volume is offline 
-54 Attempt to open locked file for writing 
-55 Specified volume is already mounted and online 
-56 Specified drive number doesn't match any number 

in the drive queue 
-57 Volume lacks Macintosh-format directory 
-58 External file system 
-59 Problem during rename 
^0 Bad master directory block 
-61 Read /write permission doesn't allow writing 
-108 Insufficient memory available 
-120 Directory not found 
-121 Too many working directories open 
-122 Attempted to move into offspring 
-123 Not an HPS volume 
-124 Server volume has been discomiected 
-127 Internal file system error 
-1300 File ID not found 
-1301 File ID akeady exists 
-1302 Specified file is a directory 
-1 303 Files are on different volimies 
-1304 Catalog has changed and catalog position record 

may be invalid 
-1306 Files are the same 

-5000 The operation has failed because the user does not 

have the correct access to the file or folder 
-5002 User authentication method is unknown 
-5003 Workstation is using an AFP version that the server 

doesn't recognize 
-5006 The operation has failed because the permission or 

deny mode conflicts with the mode in which the 

fork has already been opened 
-5015 Byte range locking has failed because the server 

cannot lock any additional ranges 
-5016 Server is not responding 
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alrpaHv lorkpfl 


af pUsejrNot Auth 


-5023 


User authentication failed (usually, password is 






not correct) 


af pObj ectTypeErr 


-5025 


Object was a file, not a directory; or, this directory is 






not a share point 


afpContainsSharedErr 


-5033 


The directory contains a share point 


afpIDNotFound 


-5034 


File ID not found 


afpIDExists 


-5035 


File ID already exists 




-5037 


Catalog has changed and search cannot be resumed 


af pSameOb j ec t Err 


-5038 


Source and destination are the same 


afpBadlDErr 


-5039 


Bad file ID 


a f p PwdExp i r ed 


-5042 


Password has expired on server 


afpInsideSharedErr 


-5043 


The directory is inside a shared directory 


afpBadDirlDType 


-5060 


Not a fixed directory ID volume 


afpCantMountMoreSrvrs 


-5061 


Maximum number of volumes have been moimted 


afpAlreadyMounted 


-5062 


Volume already motmted 


afpSameNodeErr 


-5063 


Attempt to log on to a server running on the 




same machine 
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This chapter describes how your application can use the Standard File Package to 
managed user interface for reaming and identifying fUes. H.e Standard F^e Package 
displays the dialog boxes that let the user specify the names and locations of hies to be 
saved or opened, and it reports the user's choices to your apphcation. 
The Standard File Package supports both standard and customized dialog boxes. The 
standard dialog boxes are sufficient for applications that do not require additional 
controls or other elements in the user interface. The chapter "IntroducHon to File 
Management" earlier in this book provides a detailed description of how to display 
thestandarddialogboxesbycallingtwooftheenhancedStandardFilePackage 

routines introduced in system software version 7.0. You need to read this chapter if 
your application needs to use features not described in that earUer chapter (such as 
customized dialog boxes or a special file fUter hmction). You also need to read this 
chapter if you want your application to nm in an environment where the new routines 
are not avaUable and your development system does not provide glue code that allows 
you to call the enhanced routines in earlier system software versions. 
To use this chapter, you should be familiar with the Dialog Manager, the Control 
Manager and the Finder. You need to know about the Dialog Manager if you want to 
provide a modal-dialog filter function that handles events received from ttie Event 
Manager before they are passed to theModalDialog procedure (which the Standard 
File Package uses to manage both standard and customized dialog boxes). You need to 
know about the Control Manager if you want to customize the user interface by addmg 
controls (such as radio buttons or pop-up menus). You need to know about the Fmder 
if your application supports stationery documents. See the appropriate chapters m 
Inside Macintosh: Macintosh Toolbox Essmtials for specific information about these system 
software components. 

This chapter provides an introduction to the Standard File Package and then discusses 

■ how you can display the standard file selection dialog boxes 

■ how the Standard File Package interprets user actions in those dialog boxes 

■ how to manage customized dialog boxes 

■ how to set the directory whose contents are listed in a dialog box 

■ how to aUow the user to select a volume or directory 

■ how to use the original Standard File Package routines 
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Macintosh appUcations typically have a FQe menu from which the user can save and 
open documents, via the Save, Save As, and Open commands. When theuser chooses 
Open to open an existing document, your apphcation needs to delermme which 
document to open. Similarly, when the user chooses Save As, or Save when the 
document is untitled, your application needs to ask the user for the name and location 
of the file in which the document is to be saved. 
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The Standard File Package provides a number of routines that handle the user interface 
between the user and your application when the user saves or opens a document. It 
displays dialog boxes through which the user specifies the name and location of the 
document to be saved or opened. It also allows your application to customize the dialog 
boxes and, through callback routines, to handle liser actions during the dialogs. The 
Standard File Package procedures return information about the user's choices to your 
application through a reply record. 

The Standard File Package is available in all versions of system software. However, 
significant improvements were made to the package in system software version 7.0. The 
Standard File Package in version 7.0 introduces 

■ a pair of simplified procedures (StandardGetFile and StandardPutFile) that 
you call to display and handle the standard Open and Save dialog boxes 

■ a pair of customizable procedures (CustomGetFile and CustomPutFile) that you 
call when you need more control over the interaction 

■ a new reply record (StandardFileReply) that identifies files and folders with a file 
system specification record and that accommodates the new Finder features 
introduced in system software version 7.0 

■ a new layout for the standard dialog boxes 

This section describes in detail the standard and customized user interfaces provided by 
the enhanced Standard File Package in system software version 7.0 and later. If your 
application is to run in earlier system software versions as well, you should read the 
section "Using the Original Procedures" on page 3-40. 

IMPORTANT 

If you use the enhanced routines introduced in system software 
version 7.0, you must also support the Open Documents Apple event. A 

Standard User Interfaces 

If your application has no special interface requirements, you can use the 
StandardGetFile and StandardPutFile procedures to display the standard dialog 
boxes for opening and saving documents. 

Opening Files 

You use the StandardGetFi le procedure when you want to let the user select a file to 
be opened. Figure 3-1 illustrates a sample dialog box displayed by StandardGetFile. 

The directory whose contents are listed in the display list in the dialog box displayed by 
StandardGetFile is known as the current directory. In Figure 3-1, the current 
directory is named "Tropical." The user can change the current directory in several ways. 
To ascend the directory hierarchy from the current directory, the user can click the 
directory pop-up menu and select a new directory from among those in the menu. To 
ascend one level of the directory hierarchy, the user can dick the volume icon. To ascend 
immediately to the top of the directory hierarchy, the user can click the Desktop button. 
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Figure 3-1 The default Operi dialog box 




To desceiid the directory hierarchy, the user car. double-click ar^y of the fdder names m 
the Ust (or select a folder by dicking its name once and then cUdcing the OP-^;**-)- 
Whenever the current directory changes, the list of folders and fales rs updated to reflect 
the contents of the new current directory. 

The volume on which the current directory is located is the current volume (or current 
disk), whose name is displayed to the right of the directory pop-up '"^^ « 
volume is a removable volume, the Eject button is active. The user can chck Eject to eject 
the current volume and insert another, which then becomes the current vo u^e. If the 
user inserts an uninitiaUzed or otherwise unreadable disk, the Standard File Package 
calls the Disk Initialization Manager to provide the standard user interface for 
inidalizing and naming a disk. See the chapter "Disk Initialization Manager m th,s 
book for details. 

Note that the list of files and folders always contains all folders in the current 
directory, but it might not contain all files in the current directory. When you call 
StandardGetFile, you can supply a list of the fUe types that your application 
can open, "n^e StandardGetFile procedure then displays only files of the speeded 
types You can also supply your own file filter function to help determine which files 
are displayed. (See "Writing a File Filter Function" on page 3-20 for details.) 
When the user is opening a document, StandardGetFile interprets some keystrokes 
as selectors in the displayed list. If the user presses A, for example, StandardGetFile 
selects the first item in the list that starts with the letter a (or, if no items m the list start 
with the letter a, the item that starts with the letter closest to a). The Standard File 
Package sets a timer on keystrokes: keystrokes in rapid succession form a strmg; 
keystrokes spaced in time are processed separately. See "Keyboard Equivalents on 
page 3-7 for a complete list of keyboard equivalents recognized by StandardGetFxle. 



Saving Files 



You use the StandardPutFile procedure when you want to let the user spedfy a 
name and location for a file to be saved. Figure 3-2 iUustrates a sample dialog box 
displayed by StandardPutFile. 
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Figure 3-2 The default Save dialog box 
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The dialog box displayed by StandardPutFile is similar to that displayed by 
St andardGetFi le, but includes three additional items. The Save dialog box 
includes a filename field in which the user can type the name under which to save 
the file. This filename field is a TextEdit field that permits all the standard editing 
operations (cut, copy, paste, and so forth). Above the filename field is a line of text 
specified by your application. 

When the user is saving a document, StandardPutFile can direct keystrokes to either 
of two targets: the filename field or the displayed list. When the dialog box first appears, 
keystrokes are directed to the filename field. If the user presses the Tab key or clicks to 
select an item in the displayed list, subsequent keystrokes are interpreted as selectors in 
the displayed list. Each time the user presses the Tab key, keyboard input shifts between 
the two targets. 

The third additional item in the Save dialog is the New Folder button. When the user 
clicks the New Folder button, the Standard File Package presents a subsidiary dialog 
box like the one shown in Figure 3-3. 



Figure 3-3 The New Folder dialog box 
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If the user asks to save a ffle under a name that already exists at the specified locafaon, 
the Standard File Package displays a subsidiary dialog box to verify that the new hie 
should replace the existing fUe, as illustrated in Figure 3-4. 



Figure 3-4 The name conflict dialog box 



Replace e»lsting "Dckees" 



Cancel ]} [ Beplace ) 



nie StandardGetFile and standardPutFile procedures always display the new 
dialog boxes. The procedures available before version7.0 (SFGetFile, SFPutFile, 
SFPGetFile. and SFPPutFile) also display the new dialog boxes when running in 
version 7.0, unless your application has customized the dialog box. For more details on 
how the version 7.0 Standard FUe Package handles earlier procedures, see Usmg the 
Original Procedures" on page 3-40. 



Keyboard Equivalents 



The standard File Package recognizes a long list of keyboard equivalents during dialogs. 



Keystrokes 

Up Arrow 

Down Arrow 

Command-Up Arrow 

Command-Down Arrow 

Command-Left Arrow 

Conmiand-Right Arrow 

Command-Shift-Up Arrow 

Coirmiand-Shift-1 

Command-Shift-2 

Tab 

Return or Enter 

Escape or Command-. 

Command-O 

Command-i) 

Command-N 

Option-Coixmiand-O or 
Option-[click Open] 



Action 

Scroll up (backward) through displayed list 
Scroll down (forward) through displayed list 
Display contents of parent directory 
Display contents of selected directory or volume 
Display contents of previous volume 

Display contents of next volume 

Display contents of desktop 

Eject disk in drive 1 

Eject disk in drive 2 

Move to next keyboard target 

Invoke the default option for the dialog box 

(Open or Save) 

Cancel 

Open the selected item 
Display contents of desktop 
Create a new folder 

Select the target of the selected alias item instead 
of opening it 



CO 
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When the user uses a keyboard equivalent to select a button in the dialog box, the 
button blinks. 

Customized User Interfaces 

The standard user interfaces provided by the StandardGetFile and StandardPutFile 
procedures might not be adequate for the needs of certain applications. To handle such 
cases, the Standard File Package provides several routines that you can use to present a 
customized user interface when opening or saving files. This section gives some simple 
examples of how you might want to customize the user interfaces and suggests some 
guidelines you should follow when doing so. 

IMPORTANT 

You should alter the standard user interfaces only if necessary. Apple 
Computer, Inc., does not guarantee future compatibility for your 
application if you use a custonuzed dialog box. A 

Saving Files 

Perhaps the most common reason to customize one of the Standard File Package dialog 
boxes is to allow the user to save a document in one of several file formats supported by 
the application. For example, a word-processing application might let the user save a 
document in the application's own format, in an interchange format, as a file of type 
' TEXT ', and so on. 

It is usually best to allow the user to select a file format from within the dialog box 
displayed in response to a Save or Save As menu command. To do this, you need to 
add items to the standard dialog box and process user actions in those new items. 

If your application supports only a few file formats, you could simply add the required 
number of radio buttons to the standard dialog box, as illustrated in Figure 3-5. The 
application presenting this dialog box supports only two file formats, its own proprietary 
format (SurfDraw) and the format used for startup screens. 

^'g"''^ 3-5 The Save dialog box customized with radio buttons 
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If your application supports more than a couple of alternate file formats, you could add a 

pop-up menu, as shown in Figure 3-6. 



Figure 3-6 The Save dialog box customized with a pop-up menu 
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Opening Files — 

Your applicaHon might also allow the user to open a number of ^ifferejt types of files. In 
this case there is less need to customize the Open dialog box than the Save dialog box 
Itaryou can simply list all the kinds of files your application supports. To avoid clutter 
in the lis! of files and'^folders, however, you might wish to filter out all but one of hose 

types. In this way, the user can dynamically select which type of file to v,ew m the hst. 

Once again, you might accomplish this by adding radio buttons or a pop-up menu to 
OpL dialog box depending on the number of different file types your application 

lupports Figu^ 3-7 illustrates a customized Open dialog box that contains a pop-up 

3. C^ly files of the indicated type (and, of course, folders) appear m the list of items 

available to open. 



Figure 3-7 The Open dialog box customized with a pop-up menu 



1q Tropical ▼ I 



D Bananas 
D Coconuts 
D Guauas 



File Format; | SurFDraui 



3 80 SC 



[ Desktop ] 
[ Cancel J 



About the Standard File Package 



3-9 



TIVO-408762 



CHAPTER 3 



Standard File Package 

For details on some techniques you can use to add items to the standard user interface 
and process user actions with those additional items, see "Customizing the User 
Interface" on page 3-16. Note in particular that Listing 3-3, Listing 3-8, and Listing 3-9 
together provide a fairly complete implementation of the pop-up menu illustrated in 
Figure 3-7. 

Note 

Remember that the user might also open one of your application's 
documents from the Finder (by double-clicking its icon, for example). As 
a result, you should in general avoid customizing the Open dialog box 
for files. ♦ 

Selecting Volumes and Directories 

Sometimes you need to allow the user to select a directory or a volim\e, not a file. For 
example, the user might want to select a directory as a first step in searching all the files 
in the directory for some important information. Similarly, the user might need to select 
a volume before backing up aU the files on that volume. 

The standard Open dialog box, however, is designed for selecting files, not volimies or 
directories. When the user selects a volume or directory from the items in the displayed 
list and clicks the Open button, the volume or directory is opened and its contents are 
displayed in the list. The standard Open dialog boxes provide no obvious mechanism for 
choosing a selected directory instead of opening it. 

To allow the user to select a directory — including the volume's root directory, the vblimne 
itself — you can add an additional button to the standard Open dialog box. By clicking 
this button, the user can select a highlighted directory, not open it. This button gives the 
user an obvious way to select a directory while preserving the well-known mechanism 
for opening directories to search for the desired directory. Figure 3-8 illustrates the 
standard Open dialog box modified to include a Select button and a prompt informing 
the user of the type of action required. 



Figure 3-8 The Open dialog box customized to allow selection of a directory 



Select a Folder: 

|Q Fruits 



CD Tropical 



>80 St 



[ Cancel ) 



[ Select "Tropical' ] 



3-10 About the Standard File Package 



TIVO-408763 



CHAPTER 3 



Standard File Package 



The Select button should display the name of the directory that »s selected the "s^/ 
^cksth button. This, togetL with the prompt displayed at the top «f he dialog box, 

he user differentiate this directory selection dialog box from the standard file 
oS^g^^^^^^^^ All the other items in the dialog box should maintam th.r standard 
^price a^ behavior. Any existing keyboard equivalents (in particular, the use of 
Strand Enter to select the default button) should be preserved. Command-S is 
tZendS a" keyboard equivalent for the new Select button, paralleling the use of 

To help maintain consistency among applications using this scheme for selectmg 
dSrSs your application should open the folder displayed m the pop-up menu f 
t^^^^oLc^e^^em and the user elides the Select button. In adc^^on J- s^^^^^ 
disable the Open button if no directory is currently selected Rgure 3-9 illustrates the 
recommended appearance of the directory selection dialog box m this case. 

Figure 3-9 The Open dialog box when no directory is selected 
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If the name of the directory is too long to fit in the Select button, you should abbreviate 
the name using an ellipsis character, as shown in Figure 3-10. 

Rgure 3-10 The Open dialog box with a long directory name abbreviated 
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See "Selecting a Directory" beginning on page 3-34 for details on how you can create and 
manage a directory selection dialog box. 

The directory selection dialog boxes illustrated here allow the user to specify the root . 
directory in a volume, which effectively selects the volume itself. However, you might 
want to limit the user's selections to the available volumes. To do that, you can create a 
volume selection dialog box, shown in Figure 3-11. 



Figure 3-1 1 A volume selection dialog box 
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Notice that the volume selection dialog box uses a prompt spediic to selecting a voliune 
and that the Open button is now a Select button. There is no need for a separate Select 
button, because the user should not be allowed to open any of the listed volumes. (For 
this same reason, the pop-up menu should not pop up if clicked.) See/'Selecting a 
Volume" on page 3-38 for instructions on implementing a volume selection dialog box. 

User Interface Guidelines 

In general, you should customize the user interface only if necessary. If you do modify 
the standard dialog boxes presented by the Standard File Package, you should keep 
these user interface guidelines in mind: 

■ Customize a dialog box only by adding items to the standard dialog boxes. Avoid 
removing existing items from the standard boxes or altering the operation of existing 
items. In particular, you should avoid modifying the keyboard eqtiivalents recognized 
by the Standard File Package. 

■ Add only those items that are necessary for your application to complete the 
requested action successfully. Avoid adding items that provide imnecessary 
information or items that provide no information at all (such as logos, icons, or 
other "window-dressing"). 

■ Whenever possible, use controls such as radio buttons or pop-up menus whose effects 
are visible within the dialog box itself. Avoid controls whose use calls subsidiary 
modal dialog boxes that the user must disnuss before continuing. 

■ Use controls or other iten\s that are already familiar to the user. Avoid using 
customized controls that are not also used elsewhere in your application. 
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Your overriding concern should be to make the customized file identification («alog 
boxes in your application as similar to the standard dialog boxes as possible whde 
providing the additional capabilities you need . 



Using the Standard File Package 



You use the Standard File Package to handle the user interface when the user mus 
specify a file to be saved or opened. You typically call the Standard Rle Package after 
the user chooses Save, Save As, or Open from the File menu. 

When saving a document, you call one of the PutFi le procedures, when opming a 
document, you call one of the GetFile procedures. The Standard FJe Package m 
version 7.0 introduces two pairs of enhanced procedures: 

. StandardPutFile and StandardGetFile, for presenting the Standard interface 
. CustomPutFile and CustomGetFile, for presenting a customized interface 
Before calling the enhanced Standard File Package procedures, verify that they are 
available by calling the Gestalt function with the gestaltStandardFileAttr 
selector. If Gestalt sets the gestaltStandardFile58 bit in the reply, the four 
enhanced procedures are available. 

If the enhanced procedures are not available, you need to use the original Standard File 
Package procedures that are available in all system software versions: 
■ SFPutFile and SFGetFile, for presenting the standard interface 
. SFPPutFile and SFPGetFile, for presenting a customized interface 
This section focuses on the enhanced procedures introduced in system software 
version 7.0. If you need to use the original procedures, see "Using the Original 
Procedures- on page 3-40. You can adapt most of the techniques shown in this section 

for use with the original procedures. In general however, the original procedures are 

slightly harder to use and somewhat less powerhil than their enhanced counterparts. 

All the enhanced procedures return the results of the dialog boxes in a new reply record, 

S t anda r dP i 1 eRep ly. 



TYPE StandardFileReply 



RECORD 

sfGood: 
sf Replacing: 
sfType: 
sfFile: 
sf Script : 
sfFlags : 
sflsFolder : 
sf IsVolume: 
sfReservedl: 
sf Reserved2 : 
END; 



Boolean; 
Boolean; 
OSType; 
FSSpec ; 

ScriptCode; 

Integer; 

Boolean ; 

Boolean; 

Longint ; 

Integer; 



{TRUE if user did not cancel} 

{TRUE if replacing file with same name) 

{file type] 

{selected file, folder, or volume) 

{script of file, folder, or volume name) 

{Finder flags of selected item) 

{selected item is a folder} 

{selected item is a volume} 

{reserved} 

{reserved} 
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. : The reply record identifies selected files with a file system specification (FSSpec) record. 

; You can pass the FSSpec record directly to the File Manager functions that recognize 

FSSpec records, such as FSpOpenDF or FSpCrea te. The reply record also contains 
additional fields that support the Finder features introduced in system software 
version 7.0. 

The s f Good field reports whether the reply record is valid — that is^ whether your 
applicadon can use the information in the other fields. The field is set to TRUE after the 
user clicks Save or Open, and to FALSE after the user clicks Cancel. 

Your application needs to look primarily at the sf File and sf Replacing fields when 
the sf Good field contains TRUE. The sf File field contains a file system specification 
record that describes the selected file or folder. If the selected file is a stationery pad, the 
reply record describes the file itself, not a copy of the file. 

The sf Replacing field reports whether a file to be saved replaces an existing file 
of the same name. This field is valid only after a call to the StandardPutFi le or 
CustomPutFiie procedure. Your application can rely on the value of this field instead 
of checking for and handling name conflicts itself. 

Note 

See "Enhanced Standard FUe Reply Record" on page 3-42 for a complete 
description of the fields of the StandardFileReply record. ♦ 

The Standard File Package fills in the reply record and retiuns when the user completes 
one of its dialog boxes — either by selecting a file and clicking Save or Open, or by 
clicking Cancel. Your application checks the values in the reply record to see what actiori 
to take, if any If the selected item is an alias for another item, the Standard File Package 
resolves the alias and places a file system specification record for the target in the 
sf File field when the user completes the dialog box. (See the chapter "Finder 
Interface" of Inside Macintosh: Macintosh Toolbox Essentials for a description of aliases.) 

Presenting the Standard User Interface 

You can use the standard dialog boxes provided by the Standard File Package to prompt 
the user for the name of a file to open or a filename and location to use when saving a 
document. Use StandardGetFile to present the standard interface when operung a 
file and StandardPutFi le to present the standard interface when saving a file. 

Listing 3-1 illustrates how your application can use StandardGetFile to elicit a file 
specification after the user chooses Open from the File menu. 

Listing 3-1 Handling the Open menu command 

FUNCTION DoOpenCmd: OSErr; 
VAR 

itryReply: StandardFileReply; {Standard File reply record} 
myTypes: SFTypeList; {types of files to display) 

myErr: OSErr; 
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rm -TEXT-- {display text files only) 

myTypes[0] := IbXl , 

StandardGetFile(NIL, 1, myTypes, myReply) ; 
IF myReply -sf Good THEN 

myErr := DoOpenFile (myReply. sf File) 

ELSE 

myErr := UsrCanceledErr ; 
DoOpenCmd := my Err ; 
END; 

If the user dismisses the dialogboxby clicking the Openbutton, t^e -pty r^ord fieM 
myReply . sf Good is set to TRUE; in that case, the function defined m lastmg M calk 
l aTpUcation-defined function DoOpenFile, passing it the f ^^Xf ^ ^^^f °^ 

ecoiS'^ontained in the reply record. For a sample definiUon of *e Oo^enFxle 
function, see the chapter "Introduction to FUe Management in this book. 

•n.e third parameter to standardGetFile is a list of file types that t^^PP-^ ^ 

list of files and folders; the second parameter is the number of items m that list of hie 

types. The list of file types is of type SFTypeList. 

TYPE SFTypeList = ARRAY [ 0 . . 3 ] OF OSType ; 

If you need to display more than four types of files, you can define a new data type tl^ 
is brge enough to hold all the types you need. For example, you can defme the data type 

MyTypeList to hold ten file types: 

TYPE MyTypeList = ARRAY [ 0 9 ] OF OSType ; 
MyTListPtr = -MyTypeList ; 

Listing 3-2 shows how to call StandardGetFile using an expanded type list. 
Listing 3-2 Specifying more tiian four file types 



FUNCTION DoOpenCmd: OSErr; 

'''^myReply StandardFileReply; {Standard File reply record} 
n,ylYpes: MyTypeList; (types of files to display) 

myErr: OSErr; 
BEGIN 

^yTypeslO] := 'TEXT-; tfirst file type to display) 

{Put other assignments here.} 

myTVpes[91 := 'RTFT'; (tenth file type to dxsplay) 

StandardGetFile (NIL, 1, MyTListPtr (inyTypes)- , myReply); 
IF myReply .sf Good THEN 

myErr := DoOpenFile (myReply . sf File) 
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ELSE 

myErr := UsrCanceledErr ; 
DoOpenCmd : = my Err ; 
END; 

Note 

To display all file types in the dialog box, pass -1 as the second 
parameter. Invisible files and folders are not shown in the dialog box 
unless you pass -1 in that pariameter. If you pass -1 as the second 
parameter when calling CustomGetFile, the dialog box also lists 
folders; this is not true when you call StandardGetFile. ♦ 

The first parameter passed to StandardGetFile is the address of a file filter function, 
a function that helps determine which files appear in the list of files to open. (In 
Listing 3-1, this address is NIL, indicating that all files of the specified type are to be 
listed.) See "Writing a File Filter Fimction" on page 3-20 for details on defining a filter 
function for use with StandardGetFile. 

Customizing the User Interface 

If your application requires it, you can customize the user interface for identifying files. 
To customize a dialog box, you should 

■ design your dialog box and create the resources that describe it 

■ write callback routines, if necessary, to process user actions in the dialog box 

n call the Standard File Package using the CustomPutFile and CustomGetFile 
procedures, passing the resource IDs of the customized dialog boxes and pointers to 
the callback routines 

Depending on the level of customizing you require in your dialog box, you may need to 
write as many as four different callback routines: 

■ a file filter function for determining which files the user can open 

■ a dialog hook function for handling user actions in the dialog boxes 

■ a modal-dialog filter function for handling user events received from the 
Event Manager 

■ an activation procedure for highlighting the display when keyboard input is directed 
at a customized field defined by yoiu: application 

To pirovide the interface illustrated in Figure 3-7, for example, you could replace the 
definition of DoOpenCmd given earlier in Listing 3-1 by the definition given in Listing 3-3. 

in addition to the information passed to StandardGetFile, CustomGetFile requires 
the resource ID of the customized dialog box, the location of the dialog box on the 
screen, and pointers to any callback routines and private data you are using. 
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Listing 3-3 



Presenting a customized Open dialog box 



FUNCTION DoOpenCmd: OSErr; 
VAR 



OSErr; 



my Reply : 
myTypes : 
my Point: 
my Err : 

CONST 

KCustomGetDialog 

BEGIN 

my Err := noErr; 
SetPt (iryPoint , 
myTypes [01 
myTypes [1] 
myTypes [2 3 
myTypes [33 



StandardFileReply; 
SFTypeList; 
Point; 



4000; 



(Standard File reply record) 
{types of files to display) 
{upper-left corner of box) 

{resource ID of custom dialog) 



-1, -1); 
• SRFD • ; 
• STUP ' ; 
'PICT* ; 
, ^rppT ' ; 



(center the dialog) 
{Surf Draw files) 
(startup screens) 
(picture files) 
(rich text format) 



CustomGetFile(.MyCustomFilePilter, 4, ^^^^^^^^^^ 

KCustomGetDialog, myPoint, @MyDlgHook, 
NIL, NIL, NIL, NIL) ; 

IF my Reply. sf Good THEN 

myErr := DoOpenFile (myReply . sf File) ; 

DoOpenCmd :== myErr; 
END; 

V» can ,Uo ^pply daU. of you, own .0 >he dlb.* ,oo««. .h«,.gh a n.w paramMer, 



■ 



Customizing Dialog Boxes 



. i„ , . nr nr • resource that defines the box itself and a 

To describe a dialog box, you supply a DLOG fe^ource m 
■ DITL • resource that defines the items in the dialog box. 

T • H ^4*owstheresourcedefinitionof thedefaultOpendialogbox,inRezmput 
Listing 3-4 shows the '^source ae . , Macintosh Programmer's 

format. (Rez is the resource compUer P'^^^^^^ ^^^^ accompanies the 
WorkshoDlMPWl.ForadescnptaonofReztormat,seememdiiu 



CO 

a. 



-0 

ED 
O 

CD 
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Listing 3-4 The definition of the default Open dialog box 



resource 'DLOG' {-6042, purgeable) 
( 

{0, 0, 166, 344}, dBoxProc, invisible, noGoAway, 0, 
-6042, " " , noAutoCenter 

}; ■ 

Listing 3-5 shows the resource definition of the default Save dialog box, in Rez 
input format. 



Listing 3-5 The definition of the default Save dialog box 



resource 'DLCX5' (-6043, purgeable) 
{ 

{0, 0, 188, 344}, dBoxProc, invisible, noGoAway, 0, 
-6043, noAutoCenter 

}; 
Note 

You can also use the stand-alone resoxirce editor ResEdit, available from 
Apple Computer, Inc., or other resource-editing utilities available from 
third-party developers to create customized dialog box and dialog item 
list resources. ♦ 

You must provide an item list (in a ' DITL * resource v^ith the ID specified in the 
* DLOG ' resource) for each dialog box you define. Add new items to the end of the 
default lists. CustomGetFile expects the first 9 items in a customized dialog box to 
have the same functions as the corresponding items in the StandardGetFile dialog 
box; CustomPutFile expects the first 12 items to have the same functions as the 
corresponding items in the StandardPutFile dialog box. If you want to eliminate 
one of the standard items from the display, leave it in the item list but place its 
coordinates outside the bounds of the dialog box rectangle. 

Listing 3-6 shows the dialog item list for the default Open dialog box, in Rez input 
format. See "Writing a Dialog Hook Function" beginning on page 3-21 for a list of the 
dialog box elements these items represent. 



Listing 3-6 The Item list for the default Open dialog t>ox 



resource 'DITL ' ( -6042 ) 
{ { 

{135, 252, 155, 332), Button { enabled, "Open" }, 
{104, 252, 124, 332}, Button { enabled, "Cancel" ), 
{0, 0, 0, 0), Helpltem { disabled, HMScanhdlg {-6042}}, 
{8, 235, 24, 337}, Userltem { enabled }, 
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{32, 252, 52, 332], Button { enabled, "Eject" }, 
{60, 252, 80, 332}, Button { enabled, "Desktop" }, 
{29, 12, 159, 230}, Userltem { enabled }, 
{6, 12, 25, 230), Userltem { enabled }, 
{91, 251, 92, 333}, Picture { disabled, 11 }, 
} }; 

Listing 3-7 shows the dialog item list for the default Save dialog box, in Rez input format. 
Listing 3-7 The item list for the default Save dialog box 



resource »DITL' (-6043) 
( { 

{161, 252, 181, 332), Button { enabled, "Save** }, 
{130, 252, 150, 332), Button { enabled, "Cancel" }, 
{0, 0, 0, 0}, HelpXtem { disabled, HMScanhdlg {-6043}}, 
{8, 235, 24, 337}, Userltem { enabled }, 5. 
{32, 252, 52, 332}, Button { enabled, "Eject" }, 3. 
{60, 252, 80, 332}, Button { enabled, "Desktop" }, 

{29, 12, 127, 230}, Userltem { enabled }, J 
{6, 12, 25, 230), userltem { enabled }, g- 
{119, 250, 120, 334}, Picture { disabled, 11 } , q 
{157, 15, 173, 227), EditText { enabled, }, 
{136, 15, 152, 227), StaticText { disabled, "Save as:" }, 
{88, 252, 108, 332), Userltem { disabled }, 
} }; 

The third item in each list (HelpI tern) supplies Apple's Balloon Help for items in the 
dialog box. This third item specifies the resource ID of the ' hdlg • resource that contains 
the help strings for the standard dialog items. If you want to modify the help text of an 
existing dialog item, you should copy the origiaal • hdlg ' resource from the System 
me into your application's resource fork and modify the text in the copied resource as 
desired; then you must change the resource ID specified in HelpXtem to the resource ID 
of the copied and modified resource. To provide Balloon Help for your own items, 
supply a second ' hdlg ' resource and reference it with another help item at the end 
of the list. The existing items retain their default text (unless you change that text, 
as described). 

The default dialog item lists used by the original Standard File Package routines do not 
contain help items, but the Standard FOe Package does provide Balloon Help when you 
call those routines in system software version 7.0 and later. If you call one of the original 
routines and the specified dialog item list does not contain any help items, the Standard 
FUe Package uses its default help text for the standard dialog items. If, however, the 
dialog item Hst does contain a help item, the Standard File Package assumes that your 
appUcation provides the text for all help items, including the standard dialog iten^s. 
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Note 

The default Standard File Package dialog boxes support color. The 
System file contains 'dctb' resources with the same resource IDs. as 
the default dialog boxes, so that the Dialog Manager uses color graphics 
ports for the default dialog boxes. (See the chapter "Dialog Manager" 
of Inside Macintosh: Macintosh Toolbox Essentials for a description of 
the • dctb • resource.) If you create your own dialog boxes, include 
'dctb* resources. ♦ 

Writing a File Filter F unction 

A file filter function determines which files appear in the displayed list when the user 
is opening a file. Both StandardGetFile and CustomGetFile recognize file 
filter fvmctions. 

When the Standard File Package is displaying the contents of a voIim\e or folder, it 
checks the file type of each file and filters out files whose types do not match your 
application's specifications. (Your application can specify which file types are to be 
displayed through the typeList parameter to either StandardGetFile or 
CustomGetFile, as described in "Presenting the Standard User Interface" begiiming on 
page 3-14.) If your application also supplies a file filter function, the Standard File 
Package calls that function each time it identifies a file of an acceptable type. 

The file filter function receives a pomter to the file's catalog information record 
(described in the chapter "File Manager" in this book). The function evaluates the 
catalog entry and returns a Boolean value that determines whether the file is filtered 
(that is, a value of TRUE suppresses display of the filename, and a value of FALSE 
allows the display). If you do not supply a file filter function, the Standard File Package 
displays all files of the specified types. 

A file filter function to be called by StandardGetFile must use this syntax: 

FUNCTION MyStandardFileFilter (pb: CInfoPBPtr) : Boolean; 

The single parameter passed to your standard file filter function is the address of a 
catalog information parameter block; see the chapter "File Manager" in this book for a 
description of the fields of that parameter block. 

When CustomGetFile calls your file filter function, it can also receive a pointer to any 
data that you passed in through the call to CustomGetFile. A file filter function to be 
called by CustomGetFile must use this syntax: 

FUNCTION MyCustomFileFilter {pb: CInfoPBPtr; myDataPtr: Ptr) : 

Boolean; 

Listing 3-8 shows a sample file filter function to be called by CustomGetFile. You 
might define a file filter function like this to support the custom dialog box illustrated in 
Figure 3-7, which lists files of the type shown in the pop-up box. 
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Listing 3-8 A sample file filter function 



END; 



FUNCTION MyCustomFileFilter (pb: CInfoPBPtr; n^DataPtr: Ptr) : Boolean; 

^ i^^. - TRUE- {default: don't show the file} 

MyCustomFileFilter :- TRUE, 

IF pb-.ioFlFndrlnfo.fdType = gTypesArray [gCurrentlVpel THEN 
MyCustomFileFilter := FALSE; «Bhow the fixe) 

In Usting 3-8, the appUcation global variable gCurrentType contains the index m 
the array g^pesA^ray of the currently selected file type. If the type of a fi^e passed ,n 
for evaluation matches the current file type, the fUter rehims FALSE, mdicahng that 
StandardGetFile should put it in the list. See Listing 3-9 (page 3-27) for an example 
of how you can use a dialog hook function to change the value of gCurrentType 
according to user selections in the pop-up menu control. 

Writi ng a Dialog Hook Function 

A dialog hook function handles item selections in a dialog box. It receives a pointer to 
the dialog record and an item number from the ModalDialog procedure via tt>e 
Standard File Package each time the user selects one of the dialog items Your d.alog 
hook function checlS the item number of each selected item, and then exther handles the 
selection or passes it back to the Standard File Package. 

If you provide a dialog hook hmction, CustomPutFile and CustomGetFile call 
your function immediately after calling ModalDialog. They pass your function the 
item number rehimed by ModalDialog, a pointer to the dialo^-record, and a pomter 
to the data received from your application, if any The dialog hook function must use 
this syntax: 

FUNCTION MyDlgHook (item: Integer; theDialog: DialogPtr; 

myDataPtr: Ptr): Integer; 

Your dialog hook hmction returns as its function result an integer that is either the item 
number passed to it or some other item number. If it rehims one of the item numbers m 
the following list of constants, the Standard File Package handles the seized item as 
described later in this section. If your dialog hook hmction does not handle a selection, it 
should pass the item number back to the Standard FUe Package for processmg by settmg 
its rehim value equal to the item number. 

CONST {items that appear in both the Open and Save dialog boxes) 
sfltemOpenButton = 1; tSave or Open button) 



sf ItemCancelButton = 2 

sfltemBalloonHelp = ^ 

sf ItemVoliuneUser = ^ 

sfltemEjectButton = 5 

sf ItemDesktopButton = 6 

sfltemFileListUser = 7 
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siltemPopUpMenuUser = 8; {directory pop-up menu} 

sfltemDividerLinePict = 9; {dividing line between buttons} ' 

{items that appear in Save dialog boxes only} 

sfltemFileNameTextEdit = 10; {filename field} 

sfltemPromptStaticText = 11; { filename prompt text area} 

sfltemNewFolderUser = 12; {New Folder button} 

You must write your own dialog hook jfunction to handle any items you have added to 
the dialog box. 

Note 

The constants that represent disabled items (sf ItemBalloonHelp, 
SfltemDividerLinePict, and sfltemPromptStaticText) haveno 
effectbutthey are defined in the header files for the sake of completeness. ♦ 
The Standard File Package also recognizes a number of constants that do not represent 
any actual item in the dialog list; these constants are known as pseudo-items. There are 
two kinds of pseudo-items: 

■ pseudo-items passed to your dialog hook function by the Standard File Package 

■ pseudo-items passed to the Standard File Package by your dialog hook function 
The sf HookFirstCall constant is an example of the first kind of pseudo-item. The 
Standard File Package sends this pseudo-item to your dialog hook function immediately 
before it displays the dialog box. Your funcHon typically reacts to this item number by 
performing any necessary initialization. 

You can pass back other pseudo-items to indicate that you've handled the user selecHon 
or to request some action by the Standard File Package. For example, if the list of 
files and folders must be rebuilt because of a user selection, you can pass back the 
pseudo-item sf HookRebuildList. Similarly, when your application handles the 
selecHon and needs no further action by the Standard File Package, it should return 
sf HookNullEvent. When the dialog hook function passes either sf HookNullEvent 
or an item number that the Standard File Package doesn't recognize, it does nothing. 
The Standard File Package recognizes these pseudo-item numbers: 

CONST {pseudo-items available prior to version 7.0} 

sf HookFirstCall = -1; {initialize display} 

sfHookCharOffset = $1000; {offset for character input} 

sf HookNullEvent = loO; {null event} 

sf HookRebuildList = loi; {redisplay, list} 

sfHookFolderPopUp = 102; {display parent-directory menu} 

sfHookOpenFolder = 103; {display contents of } 

{ selected folder or volume} 

{additional pseudo-items introduced in version 7.0} 
sfHookLastCall = -2; (clean up after display} 
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fHookOpenAlias = 104 

fHookGoToDesktop = 105 

fHookGoToAliasTarget = 106 

fHookGoToParent = 107 

fHookOoToNextDrive = 108 

;fHookGoToPrevDrive = 109 

ifHookChangeSelection = 110 

jfHookSetActiveOf fset = 200 



(resolve alias} 
{display contents of desktop} 
{select target of alias} 
(display contents of parent} 
(display contents of next drive} 
(display contents of previous drive} 
(select target of reply record} 
(switch active item} 



The Standard File Package uses a set of modal-dialog filter functions (described in 
"Writing a Modal-Dialog Filter Function" on page 3-28) to map user actions durmg 
the dialog onto the defined item numbers. Some of the mapping is indirect. A cUck of 
the Open button, for example, is mapped to sf itemOpenButt on only if a file is 
selected in the display list. If a folder or volume is selected, the Standard File Package 
maps the selection onto the pseudo-item sf HookOpenFolder. 
The lists that follow summarize when various items and pseudo-items are generated 
and how they are handled. The descriptions indicate the simplest mouse action that 
generates each item; many of the items can also be generated by keyboard actions, as 
described in "Keyboard Equivalents" on page 3-7. 



Note 

Any indicated effects of passing back these constants do not occur until 
the Standard File Package receives the constant back from your dialog 
hook function. ♦ 

Constant descriptions 

s f I t emOpenBu t t on 

Generated when the user clicks Open or Save while a filename is 
selected. The Standard File Package fills in the reply record (setting 
sf Good to TRUE), removes the dialog box, and returns. 

sf ItemCancelButton _ ^ . , r>.i i 

Generated when the user clicks Cancel. The Standard File Package 
sets sf Good to FALSE, removes the dialog box, and returns. 

sfltemVolumeUser . 

Generated when the user clicks the volume icon or its name, ine 
Standard File Package rebuilds the display list to show the contents 
of the folder that is one level up the hierarchy (that is, the parent 
directory of the current parent directory). 

sfltemEjectButton , ^ , 

Generated when the user dicks Eject. The Standard File Package 
ejects the volume that is currently selected. 

sf ItemDesktopButton . 

Generated when the user clicks the Drive button m a customized 
dialog box defined by one of the earlier procedures. You never 
receive this item number with the new procedures; when the user 
clicks the Desktop button, the action is mapped to tiie item 
s fHookGoToDesktop, described later in this section. The Standard 
File Package displays the contents of the next drive. 
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sf ItemFileListUser 

Generated when the user clicks an item in the display list. The 
Standard File Package updates the selection and generates this 
item for your information. 

s f I t emPopUpMenuU s er 

Never generated. The Standard File Package's modal-dialog filter 
function maps clicks on the directory pop-up menu to 
s fHookFolder Popup, described later in this section. 

s f 1 1 emFi 1 eNameText Edi t 

Generated when the user clicks the filename field. TextEdit and the 
Standard File Package process mouse clicks in the fOename field, 
but the item number is generated for your information. 

sf IteinNewFolderUser- 

Generated when the user clicks New Folder. The Standard File 
Package displays the New Folder dialog box. 

The pseudo-items are messages that aUow your application and the Standard File 
Package to commuiucate and support various features added since the original design 
of the Standard File Package. 

The Standard File Package generates three pseudo-items that give your application the 
chance to control a customized display. 

Constant descriptions 

sfHookFirstCall 

Generated by the Standard File Package as a signal to your dialog 
hook function that it is about to display a dialog box. If you 
want to initialize the display, do so when you receive this item. 
You can specify the current directory either by returning 
sf HookGoToDesktop or by changing the reply record and 
returning sfHookChangeSelect ion. , ^ 

s f HookLastCal 1 Generated by the Standard File Package as a signal to your dialog 
hook function that it is about to remove a dialog box. If you created 
any structures when the dialog box was first displayed, remove 
them when you receive this item. 

s f HookNul lEvent 

Issued periodically by the Standard File Package if no user action 
has taken place. Yotu* application can use this null event to perform 
any updating or periodic processing that might be necessary. 

Your application can generate three pseudo-items to request services from the Standard 
File Package. 

Constant descriptions 

s f HookRebu i IdLi st 

Returned by yotir diialog hook function to the Standard File Package 
when it needs to redisplay the file list. Your application nught need 
to redisplay the list if, for example, it allows the user to change the 
file types to be displayed. The Standard File Package rebuilds and 
displays the list of files that can be opened. 
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sfHookChangeSelection , ^ j j t^m ti i ^ ^ffo^ 

Returned by your application to the Standard File Package after 
your appUcation changes the reply record so that it describes a 
different fQe or folder. (You'll need to pass the address of the reply 
record in the yourDataPtr field if you want to do this.) The 
Standard File Package rebuilds the display list to show the contents 
of the folder or volume containing the object described in the reply 
record. It selects the item described in the reply record. 

sfHookSetActiveOffset ^ j ,^„Hc 

Your appUcation adds this constant to an item number and sends 
the result to the Standard File Package. The Standard File Package 

activates that item in the dialog box, making it the target of 
keyboard input. This constant allows your application to activate a 
specific field in the dialog box without expUcit input from the user. 
The Standard File Package's own modal-dialog filter fimctions generate a number of 
pseudo-items that allow its dialog hook functions to support various feahires mtroduced 
since the original design of the standard file dialog boxes. Except under extraordmary 
circumstances, your dialog hook function always passes any of these item numbers back ^ 
to the Standard File Package for processing. g 



Constant descriptions © 

sfHookCharOf fset . i^^for. S 

The Standard File Package adds this constant to the value of an | 
ASCII character when it's using keyboard input for item selection. o 
The Standard File Package uses the decoded ASCII character to 
select an entry in the display list. 

sfHookFolderPopUp ^ 
Generated when the user clicks the durectory pop-up menu. Ihe 
Standard File Package displays the pop-up menu showing all 

parent directories. 

SfHookOpenFolder , r i j 

Generated when the user clicks the Open button while a folder 
or volume is selected in the display list. The Standard File Package 
rebuilds the display list to show the contents of the folder 
or volume. 

sf HookOpenAlias . , . .1 11.^ 

Generated by the Standard File Package as a signal that the selected 
item is an alias for another file, folder, or volume. If the selected 
item is an aUas for a file, the Standard File Package resolves the 
alias, places the file system specification record of the target in the 
reply record, and returr\s. 

If the selected item is an alias for a folder or volume, the Standard 
File Package resolves the alias and rebuilds the display Ust to show 
the contents of the alias target. 

sfHookGoToDesktop , j j 

Generated when the user clicks the Desktop button. The Standard 
File Package displays the contents of the desktop in the display hst. 
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s f HookGoToAl iasTarget 

Generated when the user presses the Option key while opening an 
item that is an alias. The Standard File Package rebuilds the display 
list to display the volume or folder containing the alias target and 
selects the target. 

sfHookGoTo Parent ^ 

Generated when the user presses Command-Up Arrow (or 
clicks the volume icon). The Standard File Package rebuilds the 
display list to show the contents of the folder that is one level 
up the hierarchy (that is, the parent directory of the current 
parent directory). 

sfHookGoToNext Drive 

Generated when the user presses Command-Right Arrow. The 
Standard File Package displays the contents of the next volume. 

s f HookGoToPrevDr ive 

Generated when the user presses Command-Left Arrow. The 
Standard File Package displays the contents of the previous volume. 

The CustomGetFile and CustomPutFile procedures call your dialog hook 
function for item selections in both the main dialog box and any subsidiary dialog 
boxes (such as the dialog box for naming a new folder while saving a document 
through CustomPutFile). To determine whether the dialog record describes the 
main dialog box or a subsidiary dialog box, check the value of the ref Con field in 
the vmidow record in the dialog record. 

Note 

Prior to system software version 7.0, the Standard File Package did not 
call your dialog hook function during subsidiary dialog boxes. Dialog 
hook functions for the new CustomGetFile and CustomPutFile 
procedures must check the dialog window's ref Con field to determine 
the target of the dialog record. ♦ 

The defined values for the ref Con field represent the Standard File dialog boxes. 
CONST 



sfMainDialogRefCon = 


•stdf ' ; 


{main dialog box} 


sfNewFolderDialogRefCon = 


'nfdr* , 


{New Folder dialog box} 


sfReplaceDialogRefCon 


•rplc* . 


{name conflict dialog box} 


s f StiatWarnDialogRef Con = 


'Stat • 


; {stationery warning} 


sfErrorDialogRefCon = 


'err • 


; {general error report} 


s f LockWarnDi a logRe f Con = 


'lock' 


r {software lock warning} 



Constant descriptions 

SfMainDialogRefCon 

SfNewFolderDialogRefCon 

SfReplaceDialogRefCon 

sf StatVJarnDialogRefCon 



The main dialog box, either Open or Save. 
The New Folder dialog box. 

The dialog box requesting verification for replacing a 
file of the same name. 

The dialog box warning that the user is opening 
the master copy of a stationery pad, not a piece 
of stationery. 
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sf ErrorDialogRef con A dialog box reporting a general error. 

. 1 n 4:/-^r. Thpdialoe box waminc that the user IS opening a 
sf LockWarnD.alogRef con ^f^Jjf ^°^^„,,,be aUowed to save any changes. 

listine 3-9 defines a dialog hook function that handles user selections in the customized 
C dL ogtc mustrat^l inPiguxe3-7. Note that this dialog hook f^c^^^^^ 
Sitions Ly in the main dialog box, not in any subsidiary dialog boxes. 

Listing 3-9 A sample dialog hook function 
'^^^^:^^^^^^oo^ (ite.: integer; theDialog: DialogPtr; .yOataPtr: Ptr) : 



Integer; 

VAR 



n^Type: Integer; (menu item selected) 

^^dle: Handle; (needed for GetDIte. 

^Recf Rect; (needed for GetDItem) 

;:^Igno;e: Integer; (needed for GetDIten.; xgnored) 

'"""'k^popupltem = 10; (item nun^er of File Type pop-up menu, 

, . ' (bv default, return the item passed in) 

SuHyCl^Boolc, ; (tM, function is only for .,.n di.lo,) 

(DO processing of pseudo-items and your o«. .aaition.l item.) 
"1fl,:i«rstC.ll: .pseudo-it,., first ti„e function called, 

BEGIN 

GetDItexa(theDialog, kPopUpItem, ^Type, myHandle myRect) ; 
SetCtlValue(ControlHandle(myHandle) / gCurrentType) ; 
MyDlgHook := sfHookNullEvent; 

IcMy^pUpItexn: (-er selected File Type pop-up menu) 

'GlDItem(theDialog, item, mylgnore, inyHandle, inyRect) ; 
ittyType := GetCtlValue (ControlHandle (myHandle) ) ; 
IF np/Type <> gCurrentType THEN 
BEGIN 

gCurrentType := myType; 
MyDlgHook := sfHookRebuildList; 
END; 
END; 
OTHERWISE 

(ignore all other items] 



BEGIN 



END; 
END; 
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The pop-up menu is stored as a control in the application's resource fork. Values stored 
in the resource detemxine the appearance of the control, such as the pop-up title text and 
the menu associated with the control. The Dialog Manager's ModalDialog procedure 
takes care of drawing the box around the pop-up menu and the title of the dialog box. 
When the dialog hook function is first called, it simply retrieves a handle to that control 
and sets the value of the pop-up control to the current menu item (stored in the global 
variable gCurrentType). The MyDlgHook function then returns sfHookNu 11 Event to 
indicate that no further processing is required. 

When the user clicks the pop-up menu control, ModalDialog calls the standard control 
definition function associated with it. If the user makes a selection in the pop-up menu, 
MyDlgHook is called with the item parameter equal to kPopUpI tern. Your dialog hook 
function needs simply to determine the current value of the control and respond 
accordingly In this case, if the user has selected a new file type, the global variable 
gCurrentType is updated to reflect the new selection, and MyDlgHook rehims 
sf HookRebuildList to cause the Standard File Package to rebuild the list of files and 
folders displayed in the dialog box. 

For complete details on handling pop-up menus, see the chapters "Control Manager" 
and "Menu Manager" in Inside Macintosh: Macintosh Toolbox Essentials. 

Writing a Modal-Dialog Filter Function 

A modal-dialog filter function controls events closer to their source by filtering the 
events received from the Event Manager. The Standard File Package itself contains 
an internal modal-dialog filter function that maps keypresses and other user input 
onto the equivalent dialog box items. If you also want to process events at this level, 
you can supply your own filter function. 

Note 

You can supply a modal-dialog filter function orJy when you use one of 
the procedures that displays a customized dialog box (that is, 
CustomGetFile, CustomPutFile, SFPGetPile, or SFPPutFile). ♦ 
Your modal-dialog filter fimction determines how the Dialog Manager procedure 
ModalDialog filters events. The ModalDialog procedure retrieves events by calling 
the Event Manager function Ge tNextEvent. As just indicated, the Standard File 
Package contains an internal filter function that performs some preliminary processing 
on each event it receives. If you provide a modal-dialog filter function, ModalDialog 
calls your filter function after it calls the internal Standard File Package filter function 
and before it sends the event to your dialog hook function. 

You might provide a modal-dialog filter function for several reasoi\s. If you have 
custonuzed the Open or Save dialog boxes by adding one or more items, you might want 
to map some of the user's keypresses to those items in the same way that the internal 
filter function maps certain keypresses to existing items. 
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Another reason to provide a modal-dialog filter function is to avoid a problem that 
can arise if an update event is received for one of your application's windows while 
a Standard File Package dialog box is displayed. 

Note 

The problem described in the following paragraph occurs only in system 
software versions earlier than version 7.0. The internal modal-dialog 
fater function installed by the Standard File Package when running in 
version 7.0 and later avoids the problem by passing the update event to 
your dialog filter and, if your filter doesn't handle the event, mapping it 
to a null event. ♦ 

When ModalDialog calls GetNextEvent and receives the update event, 
ModalDialog does not know how to respond to it and therefore passes the update 
event to the Standard File Package's internal filter function. The internal fQter function 
cannot handle the update event either. As a result, if you do not provide your own 
modal-dialog filter function that handles the update event, that event is never cleared. 
The next time ModalDialog calls GetNextEvent, it receives the same update event. 
ModalDialog never receives a null event, so your dialog hook funcHon never performs 
any processing in response to the sfHook>3u 11 Event pseudo-item. You can solve this 
problem by providing a modal-dialog filter function that handles the update event or 
changes it to a null event. See Listing 3-10 for details. 

A modal-dialog filter function used with SFPGetFile and SFPPutFile is declared like 
any filter function passed to ModalDialog. Your function is passed a pointer to the 
dialog record, a pomter to the event record, and the item number. (The modal-dialog 
filter function is described in the chapter "Dialog Manager" in Inside Macintosh: 
Macintosh Toolbox Essentials.) 

FUNCTION MyModalFilter (theDialog: DialogPtr; 

VAR theEvent: EventRecord; 

VAR itemHit: Integer): Boolean; 

The modal-dialog filter function used with CustomGetFile and CustomPutFile 
requires an additional parameter, a pointer (inyDataPtr) to the data received from 
your application, if any. 

FUNCTION MyModalFilterYD (theDialog: DialogPtr; 

VAR theEvent: EventRecord; 
VAR itemHit: Integer; 
myDataPtr: Ptr) : Boolean; 

Your modal-dialog filter function returns a Boolean value that reports whether it 
handled the event. If your function returns a value of FALSE, ModalDialog 
processes the event through its own filters. If your function rehims a value of TRUE, 
ModalDialog returns with no further action. 
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The CustomGetFile and CustomPutFile procedures call your filter function to 
process events in both the main dialog box and any subsidiary dialog boxes (such as the 
dialog box for naming a new folder while saving a doounent through CustomPutFile). 
To determine whether the dialog record describes the main dialog box or a subsidiary 
dialog box, check the value of the ref Con field in the window record in the dialog record, 
as described in "Writing a Dialog Hook Fimction" beginrung on page 3-21 . 

Listing 3-10 shows how to define a modal-dialog filter function that prevents update 
events from clogging the event queue. 

Listing 3-10 A sample modal-dialog filler function 



FUNCTION MyModalFilter (theDialog: DialogPtr; VAR theEvent : EventRecord; 

VAR itemHit: Integer) : Boolean; 

BEGIN 

MyModalFilter := FALSE; {we haven't handled the event yet) 

IF theEvent .v;hat = updateEvt THEN 

IF IsAppWindow(WindowPtr (theEvent .message) ) THEN 
BEGIN 

DoUpdateEvent (WindowPtr (theEvent .message) ) ; 
MyModalFilter := TRUE; {we have handled the event} 

END; 

END; 

If this fOter function receives an update event for a window other than the Standard File 
Package dialog box, it calls the application's routine for handling update events 
(DoUpdateEvent) and returns TRUE to indicate that the event has been handled. See 
the chapters "Event Manager" and "Window Manager" in Inside Macintosh: Macintosh 
Toolbox Essentials for complete details on handling update events. 

Writing an Activation ProcecJure 

The activation procedure controls the highlighting of dialog items that are defined by 
your application and can receive keyboard input. Ordinarily, you need to supply an 
activation procedure only if your application builds a list from which the user can select 
entries. The Standard File Package supplies the activation procedure for the file display 
list and for all TextEdit fields. You can also use the activation procedure to keep track of 
which field is receiving keyboard input, if your application needs that information. 

The target of keyboard input is called the active field. The two standard keyboard-input 
fields are the filename field (present only in Save dialog boxes) and the display list. Unless 
you override it through your own dialog hook ftmction, the Standard File Package 
handles the highlighting of its own items and TextEdit fields. When the user changes the 
keyboard target by pressing the mouse button or the Tab key, the Standard File Package 
calls your activation procedure twice: the first call specifies which field is being 
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deactivated, and the second specifies which field is being activated. Your application is 
responsible for removing the highlighting when one of its fields becomes inactive and 
for adding the highUghting when one of its fields becomes active. The Standard File 
Package can handle the highlighting of all TextEdit fields, even those defined by your 
application. 

The activation procedure receives four parameters: a dialog pointer, a dialog item 
number, a Boolean value that specifies whetiier the field is being activated (TRUE) or 
deactivated (FALSE), and a pointer to your own data. 

PROCEDURE MyActivateProc (theDialog: DialogPtr; itemNo: Integer; 

activating: Boolean; myDataPtr: Ptr) ; 



Setting the Current Directory 



The first time your application calls one of the Standard File Package routines, the 
default current directory (that is, tiie directory whose contents are listed in the dialog 
box) is determined by the way in which your application was launched. 
. If the user launched your application directly (perhaps by double-clicking its icon in 

the Finder), the default directory is the directory in which your application is located. 
. If the user launched your application indirectly (perhaps by double-clicking one of 

your application's document icons), the default directory is the directory m which that 

document is located. 

At each subsequent call to one of the Standard File Package routines, the default current 
directory is simply tiie directory that was current when the user completed the previous 
dialog box. You can use the function Get SFCurDir defined in Listing 3-11 to determme 
the current directory. 



Listing 3-1 1 Determining the current directory 

FXJNCTION GetSFCurDir: Longint; 
TYPE 

LonglntPtr = ^Longint; 
CONST 

CurDirStore = $398; 
BEGIN 

GetSFCurDir := LonglntPtr (CurDirStore) ^ ; 
END; 
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You can use the GetSFCurVol function defined in Listing 3-12 to determine the 
current volume. 

Listing 3-12 Determining the current volume 

FUNCTION GetSFCurVol: Integer ; 
TYPE 

IritPtr = '"Integer; 
CONST 

SFSaveDisk = $214; 
BEGIN 

GetSFCurVol := - In tPtr (SFSaveDisk) '^; 
END; 

If necessary, you can change the default current directory and volume. For example, 
when the user needs to select a dictionary fUe for a spell-checking application, the 
application might set the current directory to a directory containing document-spedfic 
dictionary files. This saves the user frbm having to navigate the directory hierarchy from 
the directory containing documents to that containing dictionary files. You can use the 
procedure SetSFCurDir defined in Listing 3-13 to set the current directory. 

Listing 3-13 Setting the current directory 

PROCEDURE SetSFCurDir (dirlD: Longint); 
TYPE 

LonglntPtr = ^Longint; 
CONST 

CurDirStore = $398; 
BEGIN 

LonglntPtr (CurDirStore) := dirlD; 
END; 

You can use the procedure Set SFCurVol defined in Listing 3-14 to set the current volume. 
listing 3-14 Setting the cun^ent volume 

PROCEDURE SetSFCurVol (vRefNum: Integer);. 
TYPE 

IntPtr = ^Integer; 
CONST 

SFSaveDisk = $214; 
BEGIN 

IntPtr (SFSaveDisk)'^ := -vRefNum; 
END; 
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Note 

Most applications don't need to alter the default current directory 
or volume. ♦ 

lfyouareusmgtheenhancedStandardFilePackageroutines,youcansetthecu^^^^ 
directory by fffling m the fields of the file system specification in the reply jecord passed 
to CstoietFile or CustomPutFile. You do this within your dialog ^ook funcUoru 
Usting 3-15 defines a dialog hook function that makes the currenUy active System Folder 
the current directory. 



Listing 3-15 Setting the current directory 



FUNCTION MyDlgHook (item: Integer; theDialog: DialogPtr; myDataPtr: Ptr) : 

Integer; 

VAR 

myReplyPtr: StandardFileReplyPtr ; 
foundVRefNum: Integer; 
f oundDirlD : Longint ; 
my Err: OSErr; 
BEGIN . ' J • 1 

MyDlgHook := iten>; (by default, return the xtem P^-^^L 

IFGetWRefCon(WindowPtr(theDialog)) <> l^onglnt (sfMaxnDialogRefCon THEN 
Exit (MyDlgHook); (this function is only for main dxalog box) 

CASE iteni OF 

sfHookFirstCall: (pseudo-item: first time function called) 

BEGIN 

myReplyPtr := StandardFileReplyPtr (myDataPtr) ; 

myErr : . FindFolder (kOnSystemDisk, kSystemFolderlVpe , 

kDontCreateFolder, f oundVRefNuTn, f oundDirlD) ; 

IF myErr = noErr THEN 
BEGIN 

myReplyPtr-. sf File. parlD := f oundDirlD; 
myReplyPtr'^.sfFile.vRefNuin := foundVRefNum; 
MyDlgHook := sfHookChangeSelection; 
END;. 

END; 
OTHERWISE 

{ignore all other items) 

; 

END; 
END; 



3-33 

Using ttie Standard File Package 

TIVO-40B786 



CHAPTER 3 



Standard File Package 

This dialog hook function installs the System Folder's volume reference number and 

parent directory ID into the file system specification whose address is passed in the 

myDataPtr parameter. Because the dialog hook function returns the constant 

sf HookChangeSelection the first time it is called (that is, in response to the 

sf HookFirstCall pseudo-item), the Standard File Package sets the current directory 

to the indicated directory when the dialog box is displayed. 



Selecting a Directory • 

You can present the recommended user interface for selecting a directory by calling the 
CustomGetFile procedure and passing it the addresses of a custom file filter function 
and a dialog hook function. See "Selecting Volumes and Directories" on page 3-10 for a 
description of the appearance and behavior of the directory selection dialog box. 

The file filter function used to select directories is quite simple; it ensures that only 
directories, not files, are listed in the dialog box displayed by CustomGetFile. 
Listing 3-16 defines a file filter function you can use for this ptirpose. 

Listing 3-1 6 A file filter function ttiat lists only directories 

FUNCTION' MyCustomFileFilter (pb: CInfoPBPtr; myDataPtr: Ptr) : Boolean; 
CONST 

kFolderBit = 4; {bit set in ioFlAttrib for a directory) 

BEGIN {list directories only} 

MyCustomFileFilter := NOT BTst (pb^ . ioFlAttrib, kFolderBit); 
END; 

The function MyCustomFileFi Iter simply inspects the appropriate bit in the file 
attributes (ioFlAttr ib) field of the catalog information parameter block passed to it. If 
the directory bit is set, the file filter function returns FALSE, indicating that the item 
should appear in the list; otherwise, the file filter function returns TRUE to exclude the 
item from the fist. Because a volume is identified via its root directory, volumes also 
appear in the list of items in the dialog box. 

The title of the Select button should identify which directory is available for selection. 
You can use the SetButtonTitle procedure defined in Listing 3-17 to set the title 
of a button. 

Your dialog hook function calls the Se tBut tonTi 1 1 e procedure to copy the trtmcated 
title of the selected item into the Select button. This title eliminates possible user 
confusion about which directory is available for selection. If no item in the list is selected, 
the dialog hook function uses the name of the directory shown in the pop-up menu as 
the title of the Select button. 
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Listing 3-17 Setting a button's title 



PROCEDURE SetButtonTitle (ButtonHdl: Handle; name: Str255; ButtonRect: Rect) ; 
VAR 

result: Integer; {result of TruncString) 

width: integer; {width available for name of directory] 

BEGIN 

gPrevSelectedName := name; 

WITH ButtonRect DO x v 

width := (right - left) - (StringWidth C Select " " M + CharWidth( )); 
result := TruncString (width, name, smTruncMiddle) ; 
SetCTitle(ControlHandle (ButtonHdl), CONCAT (» Select name, 
ValidRect (ButtonRect ) ; 
END; 

The SetButtonTitle procedure is passed a handle to the button whose title is to be 
changed, the name of the directory available for selection, and the button's enclosing 
rectangle. The global variable gPrevSelectedName holds the full directory name, 
before truncation. 

A dialog hook function manages most of the process of letting the user select a director. 
Listing 3-18 defines a dialog hook function that handles user selections in the dialog box. 

Listing 3-1 8 Handling user selections in the directory selection dialog box 



FUNCTION MyDlgHook (item: Integer; theOialog: DialogPtr; myDataPtr: Ptr) : 
Integer; 

CONST 

kGetOirBTN = 10; {Select directory button) 
TYPE 

SFRPtr = ^StandardFileReply; 

VAR 

myType: Integer; {menu item selected) 

inyHandle: Handle; {needed for GetDItem) 

nr/Rect: Rect; {needed for GetDItem) 

myName:. Str255; 

ntyPB: CInfoPBRec; 

my SFRPtr: SFRPtr; 

myErr: OSErr; 

BEGIN ^ - , 

MyDlgHook := item; {default, except in special cases below) 

IF GetWRefCon(WindowPtr(theDialog)) <> Longint (sfMainDialogRefCon) THEN 
Exit (MyDlgHook); {this function is only for main dialog box) 

GetDItem (theDialog, kGetDirBTN, myType, myHandle, myRect) ; 
IF item = sfHookFirstCall THEN 
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. BEGIN 

' {Determine current folder name and set title of Select button.} 
WITH myPB DO 
BEGIN 

ioCompletion := NIL; 
ioNainePtr := QmyName; 
ioVRefNum := GetSFCurVol; 
ioFDirlndex := - 1; 
ioDirlD := GetSFCurDir; 
END; 

myErr := PBGetCatInf o {QmyPB, FALSE); 
SetButtonTitle (myHandle, myName, myRect) ; 

END 
ELSE 

BEGIN 

{Get mySFRPtr .from 3rd parameter to hook function.) 

mySFRPtr := SFt^Ptr (myDataPtr ) ; - 

{Track name of folder that can be selected.) 

IF (mySFRPtr'^. sflsFolder) OR (mySFRPtr^ . sflsVolume) THEN 

myName := mySFRPtr'^ . sf File .name 
ELSE 

BEGIN 

WITH myPB DO 
BEGIN 

ioCompletion := NIL; 
ioNamePtr := ©myName; 

ioVRefNum := mySFRPtr"^ . sf File .vRefNum; 
ioFDirlndex := -1; 

ioDrDirlD := mySFRPtr^ .sf File .parlD; 
END; 

myErr := PBGetCatInf o (@myPB, FALSE); 
END; 

{Change directory name in button title as needed.) 
IF myName <> gPrevSelectedName THEN 

SetButtonTitle (myHandle, myName, myRect); 



CASE item OF 

kGetDirBTN: {force return by faking a cancel) 

MyDlgHook := sf ItemCancelButton ; 
sf ItemCancelButton : 

gDirSelectionFlag := FALSE; {flag no directory was selected) 
OTHERWISE 

END; {CASE) 
END; 

END; 
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The MyDlgHook dialog hook function defined in Listing 3-18 calls the Ble Manage 
Teton PBGetCat inf o to retrieve the name of the directory to be selected. Wh n the 
dS^othook hmction is first called (that is, when iten, is set to sf HookFxrstCall), 
^DlgLk determines the current volume and directory by callmg Junch^- 
Stsrcurvol and GetSFCurDir. When MyDlgHook is called ead. subsequent tune 
^DlgHook calls PBGetCat info with the volume reference number and durectory ID 
of the previously opened directory. 

When the user clicks the Select button, MyDlgHook returns the item 
!?xte.CancelButton. When the user clicks the real Cancel ^fou^J^l.^^^^ 
sets the global variable gDirSelect ionFlag to FALSE, mdicatrng *at ^^e "ser 
didn't sdect a directory. The function DoGetDirect ory uses that varxable to 
distinguish between clicks of Cancel and dicks of Select. 

Tl,e hmction DoGetDirectory defined in Listing 3-19 uses the file fUter faction 
^d Te dialog hook hmctions defined above to manage the directory selechon dralog 
Tox. On exit, LGetDirectory re^ms a standard file reply record descnbmg the 

selected directory. 

Listing 3-19 Presenting the directory selection dialog box 



FUNCTION DoGet:Directory: StandardFileReply ; 
VAR 



S t anda r dF i 1 eReply ; 
SFTypeList; 
Point; 
Integer? 

ModalFilterYDProcPtr ; 
Ptr; 

ActivateYDProcPtr ; 
Str255; 



{types of files to display) 
{upper-left corner of box) 



{resource ID of custom dialog box) 



myReply ; 
iny Types : 
myPoint : 
inyNumTypes: 
itiyModalFilter : 
inyActiveList : 
myActivateProc: 
myName : 
CONST 

rGetDirectoryDLOG = 128; 
BEGIN 

gPrevSelectedName := '*? 
gDirSelectionFlag := TRUE; 
inyNumTypes := -1; 
inyPoint.h := -1; 
myPoint.v := -1; 
myModalFilter := NIL; 
myActiveList := NIL.; 
myActivateProc := NIL; 

CustomGetFile(@MyCustoinFileFilter, myNumTypes, myTypes, -^^^^1^, 

rGetDirectoryDLOG, ntyPoint, SMyDlgHook, ntyModalFilter , 
myActiveList, wActivateProc, QmyReply) ; 



{initialize name of previous selection} 
{initialize directory selection flag} 
{pass all' types of files to file filter} 
{center dialog box on screen} 
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{Get the name of the directory.} 

IF;gDirSelectionFlag- AND myReply.sf IsVolume THEN 

rayName := Concat(myReply.sf File. name. •:■) 
ELSE 

myName := myReply.sf File. name; 

IF gDirSelectionFlag AND myReply.sf IsVolume THEN 

myReply.sf File. name := myName 
ELSE IF gDirSelectionFlag THEN 

myReply.sf File. name := gPrevSelectedName; 
gDirSelectionFlag := FALSE; 
DoGetDirectory := myReply; 
END; 



The DoGetDirectory function initializes the two global variables 
gPrevSelectedName and gDirSelectionFlag. As you have seen, these two 
variables are used by the custom dialog hook function. Then DoGetDirectory 

setctionri^''fK *° "7''^ the dix^ctory selection dialog box and handle user 
selections. When the user selects a directory or dicks the Cancel button, the dialog 
hook functioii reharas sf itemCancelButton and QustomGetFile exits. At that 
point, ttie reply record contains informaHon about the last item selected in the list of 
available items. 



Selecting a Volume 



You can present the recommended user interface for selecting a volume by calling the 

S^d a H^l K tr''^"'' '"'^ P^^'^S ^''^'^^^^^ °' ^ fi'^ filter function 

and a dialog hook function. See "Selecting Volumes and Directories" on page 3-10 for a 
description of the appearance and behavior of the volume selection dialog box. 

^"ction used to select volumes is quite simple; it ensures that only 
volumes, not files or directories, are Usted in the dialog box displayed by 
CustomGetFile. Listing 3-16 defines a file filter function you can use to do this. 

JilsHng 3-20 A file filler function that lists only volumes 



kFolderBit = 4; /i.-.. . . . . 

BEGIN loFlAttrib for a directory} 

{list voliunes only) 
MyCustomFileFilter := TRUE; {assume you don^t list the item, 

t P-r'^""'''' '^"°^^-^i'^> (Pb^-ioDrParlD = fsRtParlD) THEN 

MyCustomFileFilter := FALSE; 

END; 
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The function MyCustomFileFil ter inspects the appropriate b.t m the f.le attnbutes 
(ioFlAttrib) field of the catalog information parameter block passed to it If the 
dilorybitisset,MyCusto.PilePiltercheckswhethertheparent^^^^^^^^^ 
the directory is equal to f sRtParlD, which is always the parent directory ID of a 
flume's ro'ot directory. If it is, the file filter function retunjs FALSE, ^f-^^^^^^^ 
item should appear in the list of volmnes; otherwise, the hie filter function returns TRUE 
to exclude the item from the list. 

A dialog hook function for handling the items in the volume selection dialog box is 
defined in Listing 3-21 . 

Listing 3-21 Handling user selections in the volume selection dialog box 



MyDlgHook (item: Integer; theDialog: DialogPtr; inyDataPtr: Ptr) : 



FUNCTION 

Integer 



VAR 



myType : 



integer; (menu item selected} 

';;;;ndle: Handle; (needed for GetDItem) 

. myRect: Rect; {needed for GetDItem} 

Zuar^e: Str255; (new title for Open button} 

^^^i^mnHook •- item- (default, except in special cases below} 

fFTet::efc;nW«r(theOialog}, <> Longint (sfMainDialogRef Con) THEN 
Exit (MyDlgHook); (this function is only for maxn dxalog box} 

CASE item OF 

sfHookFirstCall: 
BEGIN 

{Set button title and go to desktop. } 

rnvName : = 'Select'; ^\ 
GetDItemltheDialog, sf ItemOpenButton, myOVpe, myHandle, myRect) ; 
SetCTitle(.ControlHandle(myHandle) , myName) ; 
MyDlgHook := sf HookGoToDesktop; 

sf HookGoToDesktop: d^ap Cmd-D to a null event) 

MyDlgHook := sf HookNullEvent ? 
sf HookChangeSelection : 

MyDlgHook := s f HookGoToDesktop ; 
sfHookGoToNextDrive: (map Cmd-Left Arrow to a null event) 

MyDlgHook := sfHookNullEvent ; 
sfHookGoToPrevDrive: (map Cmd-Right Arrow to a null event) 

MyDlgHook := sf HookNullEvent ; 
sf IteiuOpenButton , sf HookOpenFolder : 

MyDlgHook := sf ItemOpenButton; 
OTHERWISE 

END; 
END; 
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You can prompt the user to select a volume by calling the ftinction DoGet Volume 
defined in Listing 3-22. 



Listing 3-22 Presenting the volume selection dialog box 



FUNCTION DoGetVolume : StandardFil^Reply ; 
VAR 

my Reply: StandardFileReply ; 

myTypes: SFTypeList; {types of files to display} 

myPoint: Point; {upper-left corner of box) 

myNumTypes: Integer;' 
myModalFilter : -ModalFilterYDProcPtr ; 
myActiveList : Ptr; 
myActivateProc: ActivateYDProcPtr ; 
CONST 

. rGetVolumeDLOG =129; {resource ID of custom dialog box} 

BEGIN 

inyNumTypes := -1; (pass all types of files} 

myPoint.li := -1; {center dialog box on screen} 

my Point. V := -1; 
myModalFilter := NIL; 
myActiveList := NIL; 
myActivateProc := NIL; 

CustomGetFile (@MyCustomFileFilter , myNumTypes, myTypes, myReply, 

rGetVolumeDLOG, my Point, @MyDlgHoo}c, myModalFilter, 
myActiveList, myActivateProc, @myReply) ; 

DoGetVolume : = myReply ; 
END; 



Using the Original Procedures 



The Standard File Package still recognizes all procedures available before system 
software version 7.0 (SFGetFile, SFPutFile, SFPGetFile, and SFPPutFile). It . 
displays the new interface for all applications that don't customize the dialog boxes iri 
incompatible ways (that is, applications that specify both the dialog hook and the 
modal-dialog filter pointers as NIL and that specify no alternative dialog ID). 
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When the Standard File Package can't use the enhanced dialog box layout because an 
TppUcation customized the dialog box with the earlier procedures, U nevertheless makes 
some changes to the display: 

. It changes the label of the Drive button io Desktop and makes the desktop the root of 
the display. 

. It moves the volume icon slightly to the right, to make room for selection highlighting 

around the display list field. 
If however, a customized dialog box has suppressed the file display list (by spedfymg 
coordinates outside of the dialog box), the Standard File Package uses the earher mterface, 
on the assumption that the dialog box is designed for volume selection. 
If you need to use the procedures available before system software ver^on 7.0, you need 
to be aware of a number of differences between those procedures and the enhanced 
procedures. These are the most important differences: 

. The original procedures do not recognize some pseudo-items under previous system 
softwart versions. For example, the pseudcitem HookLastCal Us u-d 
before version 7.0. See the commaUs under "Constants" m Summary of the Standard 
File Package" (beginning on page 3-60) for information on which pseudo-items are 
universally available. 

. The original standard file reply record (type SFReply) returns a ^^-^^ing dire^^^^^ 
reference number not a volume reference number. Typically, you should immediately 
Tc^rrtTat nlber to a volume reference number and director, ID usmg GetWDInf o 
or PBGetWDInfo. Then close the working directory by callmgCloseWD or 
PBClosewa L details on these hmctions, see the chapter "File Manager" in this book. 
> Dialog hook functions used with the original procedures are not passed a 
myDataPtr parameter. 



Standard File Package Reference 



This section describes the data structures and routines that are speahc to the Standard 
File Package. The "Data Structures" section shows the Pascal data sbructures for 
the original and the enhanced Standard File reply records. The section Standard File 
Package Routines" describes routines for opening and saving files. The secbon ^ 
"AppUcation-Defined Routines" describes the routines that your appbcation can dehne 
to customize the operations of the Standard File Package routines. 



Data Structures 



The Standard File Package exchanges information with your application usmg a standard 
fUe reply record. If you use the procedures introduced in system software version 7J, you 
use a reply record of type StandardFi 1 eReply. If you use the procedures available 
before version 7.0, you must use a reply record of type SFReply. 
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Eiahanced Standard File Reply Record 

When you use one of the procedures StandardPutFile, StandardGetFile, 
CustomPutFile, or CustomGetFile, you pass a reply record of type 
StandardFileReply. 

TYPE StandardFileReply = 
RECORD 



sf Good : 


Boolean ; 


{TRUE if user did not cancel) 


sf Replacing : 


Boolean, 


{TRUE if replacing file with same name} 


sfType: 


OSType ; 


{file type} 


sf File: 


FSSpec; 


{selected file, folder, or volume) 


sf Script : 


ScriptCode; {script of file, folder, or volume name} 


sf Flags : 


Integer, 


{Finder flags of selected item) 


sf IsFolder : 


Boolean, 


{selected item is a folder} 


sf IsVolume : 


Boolean 


{selected item is a volume) 


sf Reservedl : 


Longint 


{reserved} 


sf Reserved2 : 


Integer 


{reserved} 



END; 

Field descriptions 

s f Good Reports whether the reply record is valid. The value is TRUE after 

the user clicks Save or Open; FALSE after the user clicks Cancel. 
When the user has completed the dialog box, the other fields in the 
reply record are valid only if the s f Good field contains TRUE. 

sf Replacing Reports whether a file to be saved replaces an existing file of the same 
name. This field is valid only after a call to the StandardPutFile or 
CustomPutFile procedure. When the user assigns a name that 
duplicates that of an existing file, the Standard File Package asks for 
verification by displaying a subsidiary dialog box (Ulustraled in 
Figure 3-4, page 3-7). If the user verifies the name, the Standard File 
Package sets the sf Replacing field to TRUE and returns to your 
application; if the user cancels the overwriting of the file, the 
Standard File Package returns to the main dialog box. If the name 
does not conflict with an existing name, the Standard File Package 
sets the field to FALSE and returns. 

s f Type Contains the file type of the selected file. (File types are described in 

the chapter 'Tinder Interface" in Inside Macintosh: Macintosh Toolbox 
Essentials.) Only StandardGetFile and CustomGetFile rettxm a 
file type in this field. 

s f Fi 1 e Describes the selected file, folder, or volume with a file system 

specification record, which contains ia volume reference number, 
parent directory ID, and name. (See the chapter 'Tile Manager" in 
this book for a complete description of the file system specification 
record.) If the selected item is ah alias for another item, the Standard 
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sfScript 



sf Flags 



sf IsFolder 

sf IsVolume 

sfReservedl 
sfReserved2 



File Package resolves the aUas and places the file system 
specification record for the target in the sf File field when the 
user completes the dialog box. If the selected file is a stationery 
pad, the reply record describes the file itself, not a copy of the hie. 
Identifies the script in which the name of the document is to be 
displayed. (This information is used by the Finder and by the 
Standard File Package.) A script code of smSystemScript (-1) 
represents the default system script. 

Contains the Finder flags from the Finder information record in the ^ 
catalog entry for the selected file. (See the chapter 'Tinder Interface 
in Inside Macintosh: Macintosh Toolbox Essentials for a description of 
the Finder flags.) This field is returned only by StandardGetFile 
and CustomGetFile. If your application supports stationery, it 
should check the stationery bit in the Finder flags to determme 
whether to treat the selected file as stationery. Unlike the Fmder, the 
Standard Ffle Package does not automatically create a document 
from a stationery pad and pass your application the new document. 
If the user opens a stationery document from within an appHcabon 
that does not support stationery the Standard FUe Package displays 
a dialog box warning the user that the master copy is bemg opened. 
Reports whether the selected item is a folder (TRUE) or a file or 
volume (FALSE). This field is meaninghil only during the execubon 
of a dialog hook function. 

Reports whether the selected item is a volume (TRUE) or a file or 

folder (FALSE). This field is meaningful only during the execution 

of a dialog hook function. 

Reserved. 

Reserved. 



Original Standard File Reply Record 



When you use one of the original Standard File Package procedures SFPutFile, 
SFGetFile, SFPPutFile, or SFPGetFile, you pass a reply record of type SFReply. 



SFReply = 

RECORD 
good : 
copy : 
fType: 
vRefNum: 
version: 
f Name : 

END; 



Boolean; 

Boolean; 

OSType ; 

Integer; 

Integer; 

Str63; 



{TRUE if user did not cancel] 

{reserved} 

{file type} 

{working directory reference number} 

{reserved} 

{filename} 
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Field descriptions 

good 



copy 
fType 



vRefNmn 
version 
fName 

Note 



Reports whether the reply record is valid. The value is TRUE after 
the user clicks Save or Open; FALSE after the user clicks Cancel 
When the user has completed the dialog box, the other fields in the 
reply record are valid only if the value of good is TRUE. 
Reserved. 

Contains the file type of the selected file. (File types are described in 
the chapter "Finder Interface" of Inside Macintosh: Macintosh Toolbox 
Essentials.) Only SFGetFile and SFPGetFile return a file type in 
this field. 

Contains the working directory reference number of the selected file. 
Reserved. 

Contains the name of the selected file. 



In spite of Its name, the vRef Num field does not contain a volume 
reference number. Instead, it contains a working directory reference 
number, which encodes both the volume reference number and the 
parent directory ID of the selected file. You can obtain the volume 
reference number and directory ID of the file by calling GetWDInf o or 
PBGetWDinf o. See the chapter "File Manager" in this book for details 
about workmg directory reference numbers. ♦ 



Standard File Package Routines 



Tills sechon descnbes the routines you can use to prompt the user for a file's name and 
location after a request to save or open a file. If your applicafion is designed to run in 
system software versions prior to version 7.0, you must use either SFGetFile or 
SFPGetFile when opening a file and either SFPutFile or SFPPutFile when saving 

If your application is designed to take advantage of feahires introduced in system 
software version 7.0 or later, you can use the new routines intended to simpUfy 
the code required to elicit a filename from the user. Tlie StandardPutFile and 
StandardGetFile procedures are simplified versions of the original procedures 
for handhng the user interface during the storing and retrieving of files The 
CustomPutFile and CustomGetFi le procedures are customizable versions of 
tne same procedures. 



Saving Files 



You can use the StandardPutFile procedure to present the standard user interface 
when the user asks to save a file. If you need to add elements to the default dialog boxes 
or exerase greater control over user actions in the dialog box, use CustomPutFile 
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If your application is designed to execute in system software versions earlier than 
version 7.0, you can use the corresponding procedures SFPutFile and SFPPutFile. 



StandardPutFile 



You can use the StandardPutFile procedure to display the default Save dialog box 
when the user is saving a file. 

PROCEDURE StandardPutFile (prompt: Str255; def aultName : Str255; 

VAR reply: StandardFileReply) ; 

prompt The prompt message to be displayed over the text field. 
defaultName 

The initial name of the file, 
reply The reply record, which StandardPut Fi le fills in before returning. co 

3 
CL 

9> 

DESCRIPTION Tj 

The St andardPutPi le procedure presents a dialog box through which the user ® 
specifies the name and location of a file to be written to. The dialog box is centered on g 
the screen. While the dialog box is active, StandardPutFile gets and handles events S" 
until the user completes the interaction, either by selecting a name and authorizing the 
save or by canceling the save. The St andardPutFi le procedure returns the user's 
input in a record of type StandardFileReply. 



CD 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for StandardPutFile are 

Trap macro Selector 

_Pack3 $0005 



SPECIAL CONSIDERATIONS 

The StandardPutFile procedure is not available in all versions of system software. 
Use the Gestal t ifunction to determine whether StandardPutFile is available before 
calling it. 

Because StandardPutFile may move memory, you should not call it at interrupt time. 



Standard File Package Reference 



3-45 



TIVO-408798 



CHAPTER 3 



Standard File Package 
CustomPutFile 



Use the CustomPutFile procedure when your application requires more control over 
the Save dialog box than is possible using StandardPutFile. 

PROCEDURE CustomPutFile (prompt: Str255; defaultName: Str255; 

VAR reply: StandardFileReply ; 
dlglD: Integer; where: Point; 
dlgHook: DlgHookYDProcPtr ; 
filterProc: ModalFilterYDProcPtr ; 
activeList: Ptr; 

activateProc : ActivateYDProcPtr ; 
yourDataPtr: UNIV Ptr); 

prompt The prompt message to be displayed ovei: the text field. 

defaultName 

The initial name of the file, 
reply The reply record, which Cus t omPu tFi le fills in before returning. 

dlglD The resource ID of a customized dialog template. To use the standard 

template, set this parameter to 0. 
where The upper-left comer of the dialog box, in global coordinates. If you 

specify the point (-1-1), CustomPutFile automaHcally centers the 

dialog box on the screen. 

dlgHook A pointer to your dialog hook function, which handles item selections 

received from the Dialog Manager. Specify a value of NIL if you have not 
added any items to the dialog box and want the standard items handled 
in the standard ways. See "Writing a Dialog Hook Function" on page 3-21 
for a description of tlie dialog hook function. 

filterProc A pointer to your modal-dialog filter function, which determines how the 

ModalDialog procedure filters events when called by the CustomPutFile 
procedure. Specify a value of NIL if you are not supplying your own 
function. See "Writing a Modal-Dialog Filter Fimction" on page 3-28 for a 
description of the modal-dialog filter function. 

act i veLi s t A pointer to a list of all dialog items that can be activated— that is, can be 
the target of keyboard input. If you supply an activeList parameter of 
NIL, Cus tomPutFi le uses the default targets (the filename field and the 
list of files and folders). If you have added any fields that can accept 
keyboard input, you must modify the list. The list is stored as an array of 
16-bit integers. The first integer is the number of items in the list. The 
remaining integers are the item numbers of all possible keyboard targets, 
in the order that they are activated by the Tab key. 
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A pointer to your activation procedure, which controls the highlighting of 
dialog items that are defined by your application and that can receive 
keyboard input. See "Writing an Activation Procedure" on page 3-30 for a 
description of the activation procedure. 

yourDataPtr 

Any 4-byte value; usually, a pointer to optional data supplied by your 
application. When Cu s t omPu t F i 1 e calls any of your callback routines, 
it adds this parameter, making the data available to your callback 
routines. If you are not supplying any data of your own, you can specify 
a value of NIL. 

DESCRirnON 

The CustomPutFile procedure is an alternative to StandardPutFile when you want 
to display a customized Save dialog box or handle the default dialog box in a custom- 
ized way. During the dialog, CustomPutFile gets and handles events (possibly with 
the assistance of application-defined callback routines) until the user completes the inter- 
action, either by selecting a name and authorizing the save operation or by canceling the 
save operation. The Cus tomPutFi le procedure returns the user's input in a record of 
type StandardFileReply. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for CustomPutFile are 
Trap macro Selector 

_Pack3 $0007 

SPEOAL CONSIDERATIONS 

The CustomPutFile procedure is not available in all versions of system software. 
Use the Gestalt function to determine whether CustomPutFile is available before 
calling it. 

Because CustomPutFi le may move memory, you should not call it at interrupt time. 



SFPutFile 



Use the SFPutFile procedure to display the standard Save dialog box when the user is 
saving a file. 

PROCEDURE SFPutFile (where: Point; prompt: Str255; 

origName: Str255; dlgHook: DlgHookProcPtr ; 
VAR reply: SFReply) ; 
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where The upper-left comer of the dialog box, in global coordinates, 

prompt The prompt message to be displayed over the text field. 
origName The initial name of the file. 

dlgHook A pointer to your dialog hook function, which handles item selections 
received from the Dialog Manager. Specify a value of NIL if you want 
the standard items handled in the standard ways. See "Writing a Dialog 
Hook Fimction" on page 3-21 for a description of the dialog 
hook function- 
reply The reply record, which SFPutFile fills in before rehirrung. 



DESCRIPTION 



The SFPut Fi ie procedure presents a dialog box through which the user specifies the 
name and location of a file to be written to. During the dialog, SFPutFile gets and 
handles events until the user completes the interaction, either by selecting a name and 
authorizing the save or by canceling the save. The SFPutFile procedure returns the 
user's input in a record of type SFReply. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for SFPutFile are 
Trap macro Selector 

_Pack3 $0001 

SPECIAL CONSIDERATIONS 

Because SFPutFile may move memory, you should not call it at interrupt time. 



SFPPutFile 



Use the SFPPutFile procedure when your application requires more control over the 
Save dialog box than is possible using SFPutFile. 

PROCEDURE SFPPutFile (where: Point; prompt: Str255; 

origName: Str255; dlgHook: DlgHookProcPtr ; 
VAR reply: SFReply; dlglD: Integer; 
filterPr.oc: ModalFilterProcPtr) ; 



The upper-left comer of the dialog box, in global coordinates. 
The prompt message to be displayed over the text field. 



where 

prompt , o X J 

origName The initial namie of the file, if any. 
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dlgHook A pomter to your dialog hook function, which handles item selectaons 

received from the Dialog Mariager. Specify a value of NIL if you have not 
added any items to the dialog box and want the standard items handled 
in the standard ways. See "Writing a Dialog Hook Function" on page 3-21 
for a description of the dialog hook function, 
reply The reply record, which SFPPutFile fills in before rehiming. 

dlglD The resource ID of a customized dialog template. To use the standard 

template, set this parameter to -3999. 
f il ter Proc A pointer to your modal-dialog filter function, which determines how the 
ModalDialog procedure filters events when called by the SFPPutFile 
procedure. Specify a value of NIL if you are not supplying your own 
function. See "Writing a Modal-Dialog Filter Function" on page 3-28 for a 
description of the modal-dialog filter function. 



DESCRimON 

The SFPPutFile procedure is an alternative to SFPutFile when you want to display 
a customized Save dialog box or handle the default dialog box in a customized way. 
During the dialog, SFPPutFi le gets and handles events (possibly with the assistance a 
application-defined callback routines) until the user completes the interaction, either by 
selecting a name and authorizing the save operation or by canceling the save operation. 
SFPPutFile rehims the user's input in a record of type SFReply. 



ASSEMBLY-LANGUAGE INFORMATION 

The h-ap macro and routine selector for SFPPutFile are 
Trap macro Selector 

_Pack3 $0003 

SPECIAL CONSIDERATIONS 

Because SFPPutFile may move memory, you should not call it at interrupt 



Opening Files 



You can use the StandardGetFile procedure to present the standard user mterface 
when the user asks to open a file. If you need to add elements to the default dialog boxes 
or exercise greater control over user actions in the dialog box, use CustomGetFile. 
If your application is designed to execute in system software versions earlier than 
version 7.0, you can use the corresponding procedures SFGetFile and SFPGetFi le. 
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You can use the StandardGetFile procedure to display the default Open dialog box 
when the user is opening a file. 

PROCEDURE StandardGetFile (fileFilter: FileFilterProcPtr ; 

numTypes: Integer; 

typeList : SFTypeList ; 

VAR reply: StandardFileReply) ; 

f ileFi Iter A pointer to an optional file filter function, provided by yovir application, 
through which StandardGetFile passes files of the specified types. 

numTypes The number of file types to be displayed. If you specify a numTypes 
value of -1, the first filtering passes files of all types. 

t yp eL i s t A list of file types to be displayed . 

reply The reply record, which S tandardGetFi le fills in before returning. 



DESCRimoN 

The StandardGetFile procedure presents a dialog box through which the user 
specifies the name and location of a file to be opened. While the dialog box is active, 
StandardGetFile gets and handles events until the user completes the interaction, 
either by selecting a file to open or by canceling the operation. S tandardGetFi le 
returns the user's input in a record of type StandardFileReply. 

The fileFilter, numTypes, and typeList parameters together determine which 
files appear in the displayed list. The first filtering is by file type, which you specify in 
the numTypes and typeList parameters. The numTypes parameter specifies the 
number of file types to be displayed. You can specify one or more types. If you specify a 
numTypes value of -1, the first filtering passes files of all types. 

The fileFilter parameter points to an optional file filter function, provided by your 
application, through which StandardGetFile passes files of the specified types. See 
"Writing a File Filter Fimction" on page 3-20 for a description of the file filter function. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for StandardGetFile are 
Trap macro Selector 

_Pack3 $0006 



SPpaAL CONSIDERATIONS 

The StandardGetFile procedure is not available in all versions of system software. 
Use the Gestalt function to determine whether StandardGetFile is available before 
calling it. 

Because StandardGetFile may move memory, you should not call it at interrupt time. 
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Call the CustomGetFile procedxire when your application requires more control over 
the Open dialog box than is possible using StandardGetFile. 

PROCEDURE CustomGetFile (fileFilter: FileFilterYDProcPtr ; 

numTypes : Integer ; 

typeList : SFTypeList ; 

VAR reply: StandardFileReply ; 

dlglD: Integer; 

where: Point; 

dlgHook: DlgHookYDProcPtr; 

f ilterProc: ModalFilterYDProcPtr ; 

activeList: Ptr; 

activateProc: ActivateYDProcPtr ; 
yourDataPtr: UNIV Ptr) ; 

fileFilter A pointer to an optional file filter function, provided by your application, 
through v/hich Cust omGetFi le passes files of the specified types. 

numTypes The number of file types to be displayed. If you specify a numTypes 
value of -1, the first filtering passes files of all types. 

typeLi St A list of file types to be displayed. 

reply The reply record, which CustomGetFi le fills in before returning. 

dlglD The resource ID of a customized dialog template. To use the standard 

template, set this parameter to 0. 

where The upper-left comer of the dialog box in global coordinates. If you 

specify the point (-1-1), CustomGetFile automatically centers the 
dialog box on the screen. 

dlgHook A pointer to your dialog hook function, which handles item selections 

received from the Dialog Manager. Specify a value of NIL if you have not 
added any items to the dialog box and want the standard items handled 
in the standard ways. See "Writing a Dialog Hook Function" on page 3-21 
for a description of the dialog hook function. 

f i 1 1 er Pr oc A pointer to your modal-dialog filter function, which determines how 

ModalDialog filters events when called by CustomGetFile. Specify a 
value of NIL if you are not supplying your own function. See "Writing a 
Modal-Dialog Filter Function" on page 3-28 for a description of the 
modal-dialog filter function. 

act i veLi s t A pointer to a list of all dialog items that can be activated — that is, made 
the target of keyboard input. The list is stored as an array of 16-bit 
integers. The first integer is the number of items in the list. The remaining 
integers are the item numbers of all possible keyboard targets, in the 
order that they are activated by the Tab key. If you supply an 
activeList parameter of NIL, CustomGetFile directs all keyboard 
input to the displayed list. 
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activateProc 

A pointer to your activation procedure, which controls the highlighting of 
dialog items that are defined by your application and that can receive 
keyboard input. See "Writing an Activation Procedure" on page 3-30 for a 
description of the activation procedure. 

yourDataPtr 

A pointer to optional data supplied by your application.. When 
CustomGetFile calls any of your callback routines, it pushes tihis 
parameter on the stack, making the data available to your callback 
routines. If you are not supplying any data of your own, specify a 
value of NIL. 



DESCRIPTION 



The CustomGetFile procedure is an alternative to StandardGetFile when you want 
to use a customized dialog box or handle the default Open dialog box in a customized 
way CustomGetFile presents a dialog box through which the user specifies the name 
and location of a file to be opened. While the dialog box is active, CustomGetFile gets 
and handles events until the user completes the interaction, either by selecting a file to 
open or by canceling the operation. CustomGetFile rehims the user's input in a record 
of typeStandardFileReply. 

The first four parameters are similar to the same parameters in StandardGetFile. 
The f ileFilter, numTypes, and typeList parameters determine which files 
appear in the list of choices. If you specify a value of -1 in the numlVpes parameter, 
CustomGetFile displays or passes to your file filter function aU files and folders (not 
just the files) at the current level of the display hierarchy. If you provide a filter function 
CustomGetFile passes it both the pointer to the catalog entry for each file to be 
processed and also a pointer to the optional data passed by your application in its call 
to CustomGetFile. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for CustomGetFile are 
Trap macro Selector 

_Pack3 $0008 

SPECIAL CONSIDERATIONS 



The CustomGetFile procedure is not available in aU versions of system software 
Use the Gestal t function to determine whether CustomGetFile is available before 
calling it. 

Because CustomGetFile may move memory, you should not caU it at interrupt time. 
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SFGetFile 



Use the SFGetFile procedure to display the default Open dialog box when the user is 
opening a file. 

PROCEDURE SFGetFile (where: Point; prompt: Str255; 

fileFilter: FileFilterProcPtr ; 
numTypes: Integer; typeList: SFTypeList; 
dlgHook: DlgHookProcPtr ; VAR reply: SFReply) ; 

where The upper-left comer of the dialog box, in global coordinates, 

prompt Ignored. 

fileFilter A pointer to an optional file filter function, provided by your application, 
through which SFGe t Fi 1 e passes files of the specified types. 

numTypes The number of file types to be displayed. If you specify a numTypes 
value of -1, the first filtering passes files of all types. 

typeList A list of file types to be displayed. 

dlgHook A pointer to your dialog hook function, which handles item selections 

received from the Dialog Manager. Specify a value of NIL if you want the 
standard items handled in the standard ways. 

reply The reply record, which SFGet Fi 1 e fills in before returning. 

DESCRIPTION 

The SFGetFile procedure displays a dialog box listing the names of a specific 
group of files from which the user can select one to be opened (as during an Open 
menu command). During the dialog, SFGetFile gets and handles events (possibly 
with the assistance of application-defined callback routines) until the user completes 
the interaction, either by selecting a file to open or by canceling the open operation. 
SFGetFile returns the user's input in a record of type SFReply. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for SFGetFile are 
Trap macro Selector 

_Pack3 $0002' 

SPECIAL CONSIDERATIONS 

Because SFGetFile may move memory, you should not call it at interrupt time. 
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Call the SFPGetFile procedure when your application requires more control over the 
Open dialog box than is possible using SFGetFile. 

PROCEDURE SFPGetFile (where: Point; prompt: Str255; 

fileFilter: FileFilterProcPtr; 

numTypes: Integer; typel-ist : SFTypeList; 

dlgHook : DlgHookProcPtr ; 

VAR reply: SFReply; dlglD: Integer; 

filterProc: ModalFilterProcPtr) ; 

where The upper-left comer of the dialog box, in global coordinates, 

prompt Ignored. 

fileFilter A pointer to an optional fUe filter function, provided by your application, 

. through which SFPGetFile passes files of the specified types. 
numTypes The number of file types to be displayed. If you specify a numTypes 

value of -1, the first filtering passes files of all types. 
typeLi s t A list of file types to be displayed. 

dlgHook A pointer to your dialog hook function, which handles item selections 

received from the Dialog Manager. Specify a value of NIL if you have not 
added any items to the dialog box and want the standard items handled 
in the standard ways. 

reply The reply record, which SFPGet Fi le fills in before returning. 

dlglD The resource ID of a customized dialog template. 

filterProc A pointer to your modal-dialog filter function, which determines how 
the ModalDialog procedure filters events when called by the 
SFPGet Fi le procedure. Specify a value of NIL if you are not supplying 
your own function. 

DESCRIPTION 

The SFPGetFile procedure is an alternative to SFGetFile when you want to display 
a customized Open dialog box or handle the default dialog box in a customized way. 
During the dialog, SFPGetFile gets and handles events (possibly with the assistance of 
application-defined callback routines) until the user completes the interaction, either by 
selecting a file to open or by canceling the open operation. SFPGetFile returns the 
user's input in a record of type SFReply. 

ASSEMBLY-LANGUAGE INFORMATION. 

The trap macro and routine selector for SFPGetFile are 
Trap macro Selector 

_Pack3 $0004 



SPEQAL CONSIDERATIONS 

Because SFPGe t Fi 1 e may move memory, you should not call it at interrupt time. 
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Application-Defined R outines 

This section describes the application-defined routines whose addresses you pass to 
some of the Standard File Package routines. You can define 

■ a file filter function for determirung which files the user can open 

■ a dialog hook function for handling user actions in the dialog boxes 

■ a modal-dialog filter function for handling user events received from the Event 
Manager 

■ an activation procedure for highlighting the display when keyboard input is directed 
at a customized field defined by your application 

File Filter Functions 

You specify a file filter function to determine which files appear in the displayed list of 
files and folders when the user is operung a file. You can define a standard or custom 
file filter. 



MyStandar dFileFilter 

Afile filter function whose address is passed to StandardGetFile should have the 
following form: 

FUNCTION MyStandardFileFilter (pb: CInfoPBPtr) : Boolean; 
pb A pointer to a catalog information parameter block. 

DESCRIPTION 

When StandardGetFile is displaying the contents of a volume or folder, it checks the 
file type of each file and filters out files whose types do not match your application's 
specificatior\s. If your application also supplies a file filter function, the Standard File 
Package calls that function each time it identifies a file of an acceptable type. 

When your file filter function is called, it is passed, in the pb parameter, a pointer to a 
catalog ir\formation parameter block. See the chapter "File Manager" in this book for a 
description of the fields of this parameter block. 

Your function evaluates the catalog information parameter block and returns a Boolean 
value that determines whether the file is filtered (that is, a value of TRUE suppresses 
display of the filename, and a value of FALSE allows the display). If you do not supply a 
file filter function, the Standard FOe Package displays all files of the specified types. 

SEE ALSO 

See "Writing a File Filter Function" on page 3-20 for a sample file filter function. 
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MyCustomFileFilter 

A file filter function whose address is passed to Cus t omGetFi le shoiild have the 
following form: 

FUNCTION MyCustomFileFilter (pb: CInfoPBPtr; myDataPtr: Ptr) : 

Boolean; 

pb A pointer to a catalog information parameter block. 

myDataPtr A pointer to the optional data whose address is passed to 
CustomGetFile. 



DESCRIPTION 

When CustomGetFile is displaying the contents of a volume or folder, it checks the file 
type of each file and filters out files whose types do not match your application's 
specifications. If your application also supplies a file filter function, the Standard File 
Package calls that function each time it identifies a file of an acceptable type. 

When your file filter function is called, it is passed, in the pb parameter, a pointer to a 
catalog infonnation parameter block. See the chapter "File Manager" in this book for 
a description of the fields of this parameter block. 

Your function evaluates the catalog information parameter block and returns a Boolean 
value that detennines whether the file is filtered (that is, a value of TRUE suppresses 
display of the filename, and a value of FALSE allows the display). If you do not supply a 
file filter function, the Standard File Package displays all files of the specified t)^es. 



SEE ALSO 

See "Writing a File Filter Function" on page 3-20 for a sample file filter ftmction. 



Dialog Hook Functions 

A dialog hook function handles user selections in a dialog box. 

MyDlgHook 

A dialog hook function should have the following form: 

FUNCTION MyDlgHook (item: Integer; theDialog: DialogPtr; 

rnyDataPtr: Ptr) : Integer; 

i t em The number of the item selected. 

theDialog A pointer to the dialog record of the dialog box. 

myDataPtr A pointer to the optional data whose address is passed to 
CustomGetFile or Cus tomPut File. 
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DESCRIPTION 

You supply a dialog hook function to handle user selections of items that you added 
to a dialog box. If you provide a dialog hook function, CustomPutFile and 
CustomGetFile call your function immediately after calling ModalDialog. They 
pass your function the item nimiber returned by ModalDialog, a pointer to the 
dialog record, and a pointer to the data received from your application, if any. 

Your dialog hook function returns as its function result an integer that is either the item 
number passed to it or some other item number. If your dialog hook function does not 
handle a selection, it should pass the item number back to the Standard File Package for 
processing by setting its return value equal to the item number. If your dialog hook 
function does handle the selection, it should pass back sfHookNu 11 Event or the 
number of some other pseudo-item. 



SEE ALSO 

See "Writing a Dialog Hook Function" on page 3-21 for a sample dialog hook function. 
Modal-Dialog Filter Functions 




eg 

Q. 



A modal-dialog filter function controls events closer to their source by filtering the =: 

events received from the Event Manager. The Standard File Package itself contains an ti 

internal modal-dialog filter function that maps keypresses and other user input onto the g- 

equivalent dialog box items. If you also want to process events at this level, you can ^ 
supply your own filter function. 



MyModalFilter 



A modal-dialog filter function whose address is passed to SFPGetFile or SFPPutFile 
should have the following form: 

FUNCTION MyModalFilter (theDialog: DialogPtr; 

VAR theEvent: EventRecord; 

VAR itemHit: Integer): Boolean; 

theDialog A pointer to the dialog record of the dialog box. 
theEvent The event record for the event. 
itemHit The number of the item selected. 

DESCRIPTION 

Your modal-dialog filter function determines how the Dialog Manager procedure 
ModalDialog filters events. The ModalDialog procedure retrieves events by calling 
the Event Manager fimction GetNextEvent. The Standard File Package contains an 
internal filter function that performs some preliminary processing on each event it 
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receives. If you provide a modal-dialog filter function, ModalDialog calls your filter 
function after it calls the internal Standard File Package filter function and before it sends 
the event to your dialog hook function. 

Your modal-dialog filter function returns a Boolean value that reports v^hether it 
handled the event. If your function returns a value of FALSE, ModalDialog processes 
the event through its own filters. If your function returns a value of TRUE, 
ModalDialog retunis with no further action. 



SEE ALSO 



See "Writing a Modal-Dialog Filter Function" on page 3-28 for a sample modal-dialog 
filter function. 



MyModalFilterYD 



A modal-dialog filter function whose address is passed to CustomGetFile or 
CustomPutPile should have the following form: 

FUNCTION MyModalFilterYD {theDialog: DialogPtr; 

VAR theEvent: EventRecord; 
VAR itemHit: Integer; 
myDataPtr: Ptr) : Boolean; 

theDialog A pointer to the dialog record of the dialog box. 
theEvent The event record for the event, 
i t emHi t The niunber of the item selected. 

myDataPtr A pointer to the optional data whose address is passed to 
CustomGetFile or CustomPutPile. 



DESCRIPTION 

Your modal-dialog filter fimction determines how the Dialog Manager procedure 
ModalDialog filters events. The ModalDialog procedure retrieves events by calling 
the Event Manager fvmction GetNextEvent. The Standard File Package contains an 
internal filter function that performs some prelinunary processing on each event it 
receives. If you provide a modal-dialog filter function, ModalDialog calls your filter 
function after it calls the internal Standard File Package filter fimction and before it sends 
the event to your dialog hook function. 

Your modal-dialog filter function returns a Boolean value that reports whether it 
handled the event. If yoiu: function returns a value of FALSE, ModalDialog processes 
the event through its ovm filters. If your function returns a value of TRUE, 
ModalDialog returns with no further action. 
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SEE ALSO 

See "Writing a Modal-Dialog Filter Function" on page 3-28 for a sample modal-dialog 
filter function. 



Activation Procedures ^ 

An activation procedure controls the higWighting of dialog items that are defined by 
your application and can receive keyboard input. 



MyActivateProc - 

An activation procedxure should have the following form: 

PROCEDURE MyActivateProc (theDialog: DialogPtr; itemNo: Integer; 

activating: Boolean; myDataPtr: Ptr) ; 

theDialog A pointer to the dialog record of the dialog box. 
itemNo The ntunber of the item selected, 
activating 

A Boolean value that specifies whether the field is being activated (TRUE) 
or deactivated (FALSE). 
myDataPtr A pointer to the optional data whose address is passed to 
CustomGetFile or CustomPutFile. 



DESCRIPTION 

Your activation procedure controls the highlighting of dialog items that are defined by 
your application and can receive keyboard input. Ordinarily, you need to supply an 
activation procedure only if your application builds a list from which the user can select 
entries. The Standard File Package supplies the activation procedure for the file display 
list and for all TextEdit fields. You can also use the activation procedure to keep track of 
which field is receiving keyboard input, if your application needs that information. 
Your application is responsible for removing the highlighting when one of its fields 
becomes inactive and for adding the highlighting when one of its fields becomes active. 
The Standard File Package can handle the highlighting of all TextEdit fields, even those 
defined by your application. 
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Summary of the Standard File Package 



Pascal Summary 



Constants 



CONST 

{Gestalt selector and reply} 
gestaltStandardFileAttr = 'stdf; 
gestaltStandardFile58 = 0; 

{standard dialog resource IDs) 
sf PutDialogID = -6043; 

sfGetDialogID = -6042; 



{Save dialog box} 
{Open dialog box} 



{items that appear in both 

sf XtemOpenButton = 

sf ItemCancelButton = 

s f I t emBa 11 oonHelp 

sf ItemVolumeUser = 

sf ItemEjectButton 

sf ItemDesktopButton = 

sf ItemFileListUser = 

sf ItemPopUpMenuUser = 

sf ItemDividerLinePict = 



the Open and Save dialog boxes} 



(Save or Open button} 

(Cancel button} 

{Balloon Help) 

{volume icon and name} 

{Eject button} 

{Des)ctop button) 

{display list) 

{directory pop-up menu) 

{dividing line between buttons} 



{items that appear in Save dialog boxes only} 



sf ItemFileNameTextEdit = 10 
sf ItemPromptStaticText = 11 
sf ItemNewFolderUser = 12 



{filename field} 

(filename prompt text area} 

(New Folder button} 



{pseudo-items available prior to version 7.0} 



sfHoo)cFirstCall 
sfHookCharOf f set 
s f HookNu 1 1 Even t 
s f HookRebu i 1 dLi s t 
sfHookFolder Popup 
sfHookOpenFolder 



-1; . (initialize display} 

$1000; (offset for character input} 

100; (null event) 

101; (redisplay list} 

102; (display parent-directory menu). 

103; (display contents of selected } 
( folder or volume} 
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{additional pseudo-items 

sfHookLastCall 

sfHookOpenAlias 

sfHookGoToDesktop 

sfHookGoToAliasTarget 

s f HookGoToPar en t 

sfHookGoToNextDrive 

sfHookGoToPrevDrive 

s f HookChange S e 1 ec t i on 

SfHookSetActiveOff set 



introduced in version 7.0} 



-2; 

104 

105 

106 

107 

108 

109 

110 

200 



{clean up after display) 
{resolve alias) 
{display contents of desktop) 
(select target of alias) 
(display contents of parent) 
(display contents of next drive) 
(display contents of previous drive) 
{select target of reply record) 
(switch active item) 



{refCon field in the window record in the dialog record) 

sfMainDialogRefCon = 'stdf*; (main dialog box) 

sfNewFolderDialogRefCon = 'nfdr*; 

sfReplaceDialogRefCon = *rplc' ; 

sfStatWarnDialogRefCon = 'stat'; 

sfErrorDialogRefCon = *err '; 

sfLockWarnDialogRefCon = 'lock'; 



(New Folder dialog box) 
{name conflict dialog box) 
(stationery warning) 
(general error report) 
(software lock warning) 




(resource IDs and item numbers of pre-7 . 0 dialog boxes) 



putDlgID 
put Save 
putCancel 
putEject 
put Drive 
putName 



= 1 
2 

= 5 



-3999; {Save dialog box) 
(Save button) 
(Cancel button) 
(Eject button) 
(Drive button) 
(filename field) 



Q- 



no 
to 



getDlgID 

getOpen 

getCancel 

getEj ect 

getDrive 

getNmList 

getScroll 



-4000; 



(Open dialog box) 
(Open button) 
(Cancel button) 
(Eject button) 
(Drive button) 
(list of names) 
(scroll bar) 
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Data Types 



Standard Jile Reply Records 



TYPE StandardFileReply 



RECORD 

sfGood: 

sf Replacing: 

sfType: 

sfFile: 

sf Script : 

sf Flags: 

sf IsFolder : 

sf IsVolume: 

sfReservedl : 

sfReserved2 : 

END; 



Boolean; 

Boolean; 

OSType ; 

FSSpec; 

ScriptCode; 

Integer; 

Boolean; 

Boolean; 

Longint ; 

Integer; 



{enhanced standard file reply record} 

{TRUE if user did not cancel} 

{TRUE if replacing file with same name} 

{file type} 

{selected file, folder, or volume) 

{script of file, folder, or voliame name} 

{Finder flags of selected item) 

{selected item is a folder} 

{selected item is a volume) 

{reserved} 

{reserved) 



SFReply 

RECORD 
good: 
copy : 
fType: 
vRefNum: 
version : 
fName: 

END; 



= {original standard file reply record) 

Boolean; {TRUE if user did not cancel) 

Boolean; {reserved) 

OSType; {file type) 

Integer; {worlcing directory reference number) 

Integer; {reserved} 

Str63; {filename) 



Standard File Type List 

SFTypeList = ARRAY[0..3] OF OSType; 

Callback Routine Pointer Tjrpes 



DlgHooJcProcPtr = 


ProcPtr; 


{dialog hook function) 




Dl gHoolcYDPr oc Pt r 


ProcPtr; 


{dialog hoolc function with 


data) 


FileFilterProcPtr = 


ProcPtr; 


{file filter function) 




FileFilterYDProcPtr = 


ProcPtr; 


{file filter function with 


data) 


ModalFilterProcPtr = 


ProcPtr ; 


{modal-dialog filter) 




ModalFilterYDProcPtr = 


ProcPtr; 


{modal-dialog filter with data) 


ActivateYDProcPtr = 


ProcPtr; 


(activation procedure) 
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Saving Files 

PROCEDURE StandardPutFile 
PROCEDURE CustomPutFile 



PROCEDURE SFPutFile 



PROCEDURE SFPPutFile 



(prompt: Str255; defaultName: Str255; 
VAR reply: StandardFileReply) ; 
(prompt: Str255; defaultName: Str255; 

VAR reply: StandardFileReply; dlglD: Integer; 

where: Point; dlgHook: DlgHookYDProcPtr ; 

filterProc: ModalFilterYDProcPtr ; 

activeList: Ptr; 

activateProc : ActivateYDProcPtr ; 
yourDataPtr: UNIV. Ptr); 
(where: Point; prompt: Str255; 
origName: Str255; dlgHook: DlgHookProcPtr; 
VAR reply: SFReply) ; 
(where: Point; prompt: Str255; 
origName: Str255; dlgHook: DlgHookProcPtr; 
VAR reply: SFReply; dlglD: Integer; 
filterProc: ModalFilterProcPtr) ; 



Opening Files 

PROCEDURE StandardGetFile 
PROCEDURE CustomGetFile 



PROCEDURE SFGetFile 



PROCEDURE SFPGetFile 



(fileFilter: FileFilterProcPtr ; 

numTypes: Integer; typeList : SFTypeList; 

VAR reply: StandardFileReply); 
(fileFilter: FileFilterYDProcPtr ; 

numTypes: Integer; typeList: SFTypeList; 

VAR reply: StandardFileReply; dlglD: Integer; 

where: Point; dlgHook: DlgHookYDProcPtr; 

f i 1 1 erPr oc : ModalFi 1 1 erYDPr ocPt r ; 

activeList: Ptr; 

activateProc : ActivateYDProcPtr; 
yourDataPtr: UNIV Ptr); 

(where: Point; prompt: Str255; 
fileFilter: FileFilterProcPtr; 
numTypes: Integer; typeList: SFTypeList; 
dlgHook: DlgHookProcPtr; VAR reply: SFReply); 

(where: Point; prompt: Str255; 
fileFilter: FileFilterProcPtr; 
nxnnTypes: Integer; typeList: SFTypeList; 
dlgHook: DlgHookProcPtr; VAR reply: SFReply; 
dlglD: integer; 

filterProc: ModalFilterProcPtr) ; 
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Application-Defined Routines 



FUNCTION MyStandardFileFilter 



FUNCTION MyCustomFileFilter 
FUNCTION MyDlgHook 

FUNCTION MyModalFilter 
FUNCTION MyModalFilterYD 
PROCEDURE MyActivateProc 



(pb: CInfoPBPtr) : Boolean; 

(pb: CInfoPBPtr; myDataPtr: Ptr) : Boolean; 

(item: Integer; theDialog: DialogPtr; 

myDataPtr: Ptr) : Integer; 
(theDialog: DialogPtr; 

VAR theEvent: EventRecord; 

VAR itemHit: Integer): Boolean; 
(theDialog: DialogPtr; 

VAR theEvent: EventRecord; 

VAR itemHit: Integer; myDataPtr: Ptr): Boolean; 
(theDialog: DialogPtr; itemNo: Integer; 
activating: Boolean; myDataPtr: Ptr); 



C Summary 



Constants 

/*Gestalt selector and reply*/ 

#define gestaltStandardFileAttr 'stdf 

#define gestaltStandardFileSS 0 



/^standard dialog resource IDs*/ 

enum {sf PutDialogID , = (-6043)}; /*Save dialog box*/ 

enum { sfGetDialogID = (-6042)}; /*Open dialog box*/ 

/*items that appear in both the Open and Save dialog boxes/* 



enum (sf ItemOpenButton = i} 

enum {sf ItemCancelButton = 2} 

enum {sf ItemBalloonHelp = 3} 

enum (sf ItemVolumeUser = 4} 

enum {sf ItemEjectButton = 5) 

enum {sf ItemDesktopButton =6} 

enum {sf ItemFileListUser = 7} 

enum {sf ItemPopUpMenuUser = 8} 

enum {sf ItemDividerLinePict =9} 



/*Save or Open button*/ 
/♦Cancel button*/ 
/♦Balloon Help*/ 
/♦volume icon and name*/ 
/♦Eject button*/ 
/♦Desktop button*/ 
'/♦display list*/ 
/♦directory pop-up menu*/ 
/♦dividing line between buttons*/ 



/♦items that appear in Save dialog boxes only*/ 
enum {sf ItemFileNameTextEdit = 10) 
enum {sf ItemPromptStaticText =11} 
enum {sf ItemNewFolderUser =12} 



/♦filename field*/ 
/♦filename prompt text area^/ 
/♦New Folder button*/ 
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/*pseudo-iteins available, prior to version 7.0*/ 



enum {sf HookFirstCall 
enum {sf HookCharOf f set 
enum {sfHookNu 11 Event 
enum {sfHookRebuildList 
enum (sf HookFolderPopUp 
enum { s f HookOpenFo 1 der 



(-1)); /*initialize display*/ 
= 0x1000) ; /*off set for character input*/ 
= 100); /*null event*/ 
= 101); /*redisplay list*/ 
= 102); /*display parent -directory menu*/ 
= 103); /*displaY contents of selected */ 
/* folder or volume*/ 



/*additional pseudo-items introduced in version 7.0*/ 



enum {sf HookLastCall 
enum {sf HookOpenAlias 
enum {sfHookGoToDesktop 
enum {sf HookGoToAliasTarget 
enum {sf HookGoToParent 
enum { s fHookGoToNext Drive 
enum { s f HookGoToPr evDr i ve 
enum { s f HookChangeSelect ion 
enum {sf HookSetActiveOf f set 



= (-2)); /*clean up after display*/ 

= 104); /*resolve alias*/ 

= 105); /*display contents of desktop*/ 

= 106); /*select target of alias*/ 

= 107); /*display contents of parent*/ 

=108); /*display contents of next drive*/ 

= 109); /*display contents of previous drive*/ 

= 110); /*select target of reply record*/ 

= 200); /*switch active item*/ 



/*refCon field in the window record in the dialog record*/ 



#define sfMainDialogRefCon * stdf ' 

#define sfNewFolderDialogRef Con 'nfdr' 

IJdefine sf ReplaceDialogRefCon 'rplC 

#define sf StatWarnDialogRef Con 'stat* 

#define sf ErrorDialogRef Con 'err ' 

#define sf LockWarnDialogRef Con 'lock' 



/*main dialog box*/ 
/*New Folder dialog box*/ 
/*name conflict dialog box*/ 
/* stationery warning*/ 
/*general error report*/ 
/* software lock warning*/ 



/*resource IDs and item numbers of pre-7,0 dialog boxes*/ 

enum {putDlgID = -3999); /*Save dialog box*/ 

enum {put Save = D; 

enum {putCancel =2); 

enum {putEject = 5); 

enum {putDrive = 6); 

enum {putName = 7 ) ; 



/*Save button*/ 
/*Cancel button*/ 
/*Eject button*/ 
/*Drive button*/ 
/*filename field*/ 



enum {getDlgID 
enum {getOpen 
enum {getCancel 
envim (getEject 
enum {get Drive 
enum {getNmList 
enum {getScroll 



-4000); /*Open dialog box*/ 

1); /*Open button*/ 

3); /*Cancel button*/ 

5) ; /*Eject button*/ 

6) ; /*Drive button*/ 

7) ; /*list of names*/ 

8) ; /* scroll bar*/ 
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Data Types 



Standard File Reply Records 

struct StandardFileReply .{ 



}; 



Boolean 

Boolean 

OSType 

FSSpec 

ScriptCode 

short 

Boolean 

Boolean 

long 

short 



sfGood; 

sf Replacing 

sfType; 

sf File; 

sf Script ; 

sfFlags; 

sf IsFolder; 

sf IsVolume; 

sfReservedl 

sfReserved2 



/♦enhanced standard file reply record*/ 
/*TRUE if user did not cancel*/ 
;/*TRUE if replacing file with same name*/ 
/*file type*"/ 

/*selected file, folder, or volume*/ 
/*script of file, folder, or volume name*/ 
/*Finder flags of selected item*/ 
/♦selected item is a folder*/ 
/*selected item is a volume*/ 

; /*reserved*/ 

; /*reserved*/ 



typedef struct StandardFileReply StandardFileReply; 



struct SFReply { 
Boolean 
Boolean 
OSType 
short 
short 
Str63 

}; 



/♦original standard file reply record*/ 

good; /*TRUE if user did not cancel*/ 

copy; /*reserved*/ 

fType; /*file type*/ 

vRefNum; /*working directory reference number*/ 

version; /*reserved*/ 

fName; /*filename*/ 



typedef struct SFReply SFReply; 

Standard File Type List 

typedef OSType SFTypeList [ 4] ; 

Callback Routine Pointer Types 

/♦dialog hook function*/ 

typedef pascal short (*DlgHookProcPtr) 

(short item, DialogPtr theDialog) ; 
/*dialog hook function with data*/ 
typedef pascal short (*DlgHookYDProcPtr) 

(short item, DialogPtr theDialog, 
void *yourDataPtr) ; 
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/*file filter function*/ 

typedef pascal Boolean ( *FileFilterProcPtr) 

(ParmBlkPtr PB) ; 

/*file filter function with data*/ 

typedef pascal Boolean (*FileFilterYDProcPtr) 

(ParmBlkPtr PB, void *yourDataPtr) ; 

/*modal-dialog filter*/ 

typedef pascal ProcPtr ModalFilterProcPtr; 

(DialogPtr theDialog, EventRecord *theEvent, 

short *itemHit) ; 

/*modal-dialog filter with data*/ 

typedef pascal Boolean (*ModalFilterYDProcPtr) 

(DialogPtr theDialog, EventRecord *theEvent, 
short *itemHit, void *yourDataPtr) ; 

/♦activation procedure*/ 

typedef pascal void (*ActivateYDProcPtr) 

(DialogPtr theDialog, 

short iteitiNo, Boolean activating, 

void *yourDataPtr) ; 



Standard File Package Routines 



Saving Files 

pascal void StandardPutFile (const Str255 prompt, const Str255 defaultName, 

StandardFileReply * reply) ; 

pascal void CustomPutFile (const Str255 prompt, const Str255 defaultName, 

StandardFileReply *reply, short dlglD, 
Point where, DlgHookYDProcPtr dlgHook, 
ModalFilterYDProcPtr f ilterProc , 
short *activeList, 
ActivateYDProcPtr activateProc, 
void *yourDataPtr) ; 

pascal void SFPutFile (Point where, const Str255 prompt, 

const Str255 origName, DlgHookProcPtr dlgHook, 
SFReply * reply) ; 

pascal void SFPPutFile ^ (Point where, const Str255 prompt, 

const Str255 origName, DlgHookProcPtr dlgHook, 
SFReply *reply, short dlglD, 
ModalFilterProcPtr. f ilterProc) ; 
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Openiifig Files 

pasG^i void StandardGetFile (const Str255 prompt, 



pascal void CustomGetFile 



pascal void SFGetFile 



pascal void SFPGetFile 



FileFilterProcPtr fileFilter, 

short niunTypes, SFTypeList typeList, 

StandardFileReply * reply) ; 

(FileFilterYDProcPtr fileFilter, 
short numTypes, SFTypeList typeList, 
StandardFileReply *reply, short dlglD, 
Point where, DlgHookYDProcPtr dlgHook, 
ModalFilterYDProcPtr filterProc, 
short *activeList, 
ActivateYDProcPtr activateProc, 
void *yourDataPtr ) ; 

(Point where, const Str255 prompt, 
FileFilterProcPtr fileFilter, short numTypes, 
SFTypeList typeList, Dl^HookProcPtr dlgHook, 
SFReply * reply) ; 

(Point where, const Str255 prompt, 
FileFilterProcPtr fileFilter, 
short niimTypes, SFTypeList typeList,* 
DlgHookProcPtr dlgHook, SFReply * reply, 
short dlglD, ModalFilterProcPtr filterProc) ; 



Application-Defined Routines 



pascal Boolean MyStandardFileFilter 

(CInfoPBPtr pb) ; 
pascal Boolean MyCustomFileFilter 

(CInfoPBPtr pb, Ptr myDataPtr) ; 
: pascal short MyDlgHook (short item, DialogPtr theDialog, 

Ptr myDataPtr); 
pascal Boolean MyModalFilter (DialogPtr theDialog, 

EventRecord *theEvent, short *itemHit) ; 
, pascal Boolean MyModalFilterYD 

(DialogPtr theDialog, 

EventRecord *theEvent, short *itemHit, 
Ptr myDataPtr); 

pascal void MyActivateProc (DialogPtr theDialog, short itemNo, 

Boolean activating, Ptr myDataPtr) ; 
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Assembly-Language Summary 



Data Structures 



New Standard File Reply Record 



0 


sfGood 


byte 


1 


sfReplacing 


byte 


2 


sfType 


long 


6 


sfFile 


70 bytes 


76 


sfScript 


word 


78 


sfFlags 


word 


80 


sflsFolder 


byte 


81 


sflsVolume 


byte 


82 


sfReservedl 


long 


86 


sfReserved2 


word 



Old Standard File Reply Record 

byte 
byte 
long 
word 
word 
64 bytes 



0 
1 
2 
6 
8 
10 



good 

copy 

fType 

vRefNum 

version 

fName 



command-valid flag 

replace existing file flag 

file type 

selected item 

display script 

Finder flags from catalog 

folder flag 

volume flag 

reserved 

reserved 



command-valid flag 

reserved 

file type 

working directory reference niunber 
reserved 

name of file (length byte followed by up to 
63 characters) 



■ 



Q. 

a 
n 

a> 

D) 
O 

to 

CD 



Trap Macros 



Trap Macro Requiring Routine Selector 



_Pack3 




Selector 


Routine 


$0001 


SFPutFile 


$0002 


SFGetFile 


$0003 


SFPPutFile 


$0004 


SFPGetFile 


$0005 


StandardPutFile 


$0006 


StandardGetFile 


$0007 


CustomPutFile 


$0008 


CustomGetFile 



Global Variables 



CurDirStore long The directory ID of the current directory. 

SFSaveDisk word The negative of the volume reference number of the current volume. 
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This chapter describes how your appUcation can use the Alias Manager to establish and 
resolve alias records, which are data structures that describe file system objects (that is, 
fUes, directories, and volumes). You create an aUas record to take a "fingerprint" of a file 
system object, usually a file, that you might need to locate again later. You can store the 
alias record, instead of a file system specification, and then let the Alias Manager find the 
file again when it's needed. The Alias Manager contains algorithms for locating files that 
have been moved, renamed, copied, or restored from backup. 

Note 

The Alias Manager lets you manage alias records. It does not directly 
manipulate Find^ aliases, which the user creates and manages through 
the Finder. The chapter "Finder Interface" in Inside Macintosh: Macintosh 
Toolbox Essentials describes Finder aliases and ways to accommodate 
them in your appUcation. ♦ 

The Alias Manager is available oiily in system software version 7.0 or later. Use the 
Gestalt function, described in the chapter "Gestalt Manager" of Inside hAacintosk 
Operating System Utilities, to determine whether the Alias Manager is present. 
Read this chapter if you want your application to create and resolve alias records. You 
might store an aUas record, for example, to identify a customized dictionary from 
within a word-processing document. When the user runs a spelling checker on the 
document, your appUcation can ask the AUas Manager to resolve the record to find the 
correct dictionary. 

To use this chapter, you should be faniiUar with the FUe Manager's conventions for 
identifying files, directories, and volumes, as described in the chapter "Introduction to 
File Management" in this book. 

This chapter begins with a description of the AUas Manager, alias records, and the search 
strategies that the Alias Manager uses to resolve an aUas record. Then this chapter shows 
how you can 

■ create alias records 

■ resolve alias records 

■ store alias records as resources 

■ get information about the target of an aUas record 



About the Alias Manager 



The Alias Manager is the part of the Operating System that helps you to locate specified 
fUes, directories, or volumes at a later timp. It stores certain information about the target 
object in an aUas record. When you later want the AUas Manager to find the target, you 
pass it the aUas record and other information regarding the type of search to perform. 
Sometimes, the AUas Manager can find the original file. In other cases, the AliasManager 
builds a list of potential matches and allows you (or the user) to select the desired file. 
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The Alias Manager creates and resolves (that is, fmds the targets of) alias records. In 
general, you should use the Alias Manager to create an alias record whenever you find 
yourself storing a-spedfic file description, such as filename and parent directory ID. The 
Alias Manager stores this information and more in the aUas record, and it also provides a 
set of search strategies for resolving the record later. The search strategies are described 
in "Search Strategies" beginning on page 4-5. You can use the Alias Manager to create, 
resolve, and (if necessary) update alias records. You can also obtain information about 
the target of an aUas record without actually resolving the alias record. 
The AHas Manager can track files and directories across volumes. If the target of an 
alias record is on an unmounted AppleShare volume, the AHas Manager automatically 
mounts the volume when it resolves the aHas. If the target object is on an unmounted 
ejectable volume, the Alias Manager prompts the user to insert the volume. 
When the AHas Manager creates an aHas record, it aUocates the storage, fiUs in the 
record, and returns a handle to it Your appHcation is responsible for storing the record 
and retrieving it when needed. Your application must also supply strategies for handlmg 
various aHas-resolution problems, described in "Resolving Alias Records" on page 4-10. 
To help you understand and use the Alias Manager, this section provides 

■ an overview of alias records 

■ a description of the search strategies the AHas Manager uses to resolve aHas records 



Alias Records 



An alias record is a data structure that describes a fHe, directory, or volume. The record 
contains 

■ location information, such as name and parent directory ID 

■ verification information, such as creation date, file type, and creator 

■ volume mounting information (that is, server and zone), if applicable 

By storing aHas records, you can allow your users to create a robust connection to a file— 

that is, a connection that can survive the moving or renaming of the target file. The 

Finder introduced in system software version 7.0, for example, stores aHas records in 

afiases created by the user to represent other files or folders. The Edition Manager uses 

aHas records to support data sharing among separate documents. 

An aHas record is a reliable way to identify a file system object when your appHcation is 

commimicating with a process that might be running on a different machine. 

The creation of an aHas record has no effect on the target of the record, except to estabHsh 

a file ID reference for the target file if one did not previously exist. (See the chapter "File 

Manager" in this book for a description of file IDs and file ID references.) 

The alias record contains only two fields of pubHc iriformation available to your 

appHcation. The bulk of the record is managed privately by the AHas Manager. 
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TYPE AliasRecord = 
RECORD 

userType: OSType; {application's signature) 

aliasSize: Integer; (size of record when created} 

{variable-length private data) 
END; 

Your application can store, in the userType field, its own signatiire or any other 
data that fits into 4 bytes. When the Alias Manager creates an alias record, it stores 0 
in that field. 

The Alias Manager stores, in the aliasSize field, the size assigned to the record at the 
time of its creation. Knowing the starting size allows you to store and retrieve data of 
your own at the end of the record (see "Customizing Alias Records" on page 4-13). An 
alias record is typically 200 to 300 bytes long. 

The private Alias Manager data includes all of the location, verification, and mounting 
information needed to resolve the alias record with the various search strategies 
described in this chapter. 

Search Strategies 

Some of the key feahues of the Alias Manager are the search strategies built into the 
alias-resolution functions. The search strategies are designed to find the original target 
of an alias record, even if the target has been moved, renamed, copied, or restored from 
backup. Which strategy you use to resolve a particular alias record usually depends on a 
number of factors, including whether you are willing to sacrifice time to find as many 
potential targets as possible and whether the target is known to be in a particular 
volume. This section describes the available search strategies. 

You can request either a relative or an absolute search. If you request an absolute search, 
you can specify whether the search should be either fast or exhaustive. (A relative search 
is always a fast search.) As you can see, tiiere are three general search strategies available 
to your application for resolving alias records: 

■ relative search (always fast) 

■ absolute fast search 

■ absolute exhaustive search 

The following sectioi^ describe these search strategies. 

Relative Searches 

During a relative search, the Alias Manager starts in a specified directory and 
searches for the target of an alias record by ascending the file system hierarchy to 
a predetermined common parent of the target and the starting directory and then 
descending the hierarchy from that common parent. 
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Suppose, for example, that you are writing a word-processing application that allows the 
user to build a customized, supplemental dictionary for each documer^t. You might 
create the dictionary as a separate document in the same directory as the doojment it 
serves. In this case, the common parent of the document and the ^^ci^^^^-T (that^^ 
the lowest-level directory that appears in the pathnames of both) is simply the directory 
containing both files. 

More generally, you might want to store all document-specific dictionary files in their 
own directory, as Ulustrated in Figure 4-1. Here, the common parent of document file 
'Tile r and its associated dictionary file "Diet T is the directory named Sample. 

Rgure 4-1 Resolving a relative path 



Documents 




Common 
parent 



Sample 



L 



Distance to 
common 
parent = 2 



Dictionary 



RIe 1 File 2 File 3 



Dicti Diet 2 Diet 3 



To resolve an alias record using a relative search, the Alias Manager needs several pieces 
of information, which are recorded in the alias record at the time you create it. The Alias 
Manager needs a relative path, that is, a path to the target from another file or directory 
on the same volume. (Relative paths don't work across volumes.) To record a relahve 
path, the Alias Manager saves the distances from the target and the startmg Me or 
directory to their common parent. The Alias Manager can later use those distances m 
conjunction with the hill pathname to conduct a relative search. 

When resolving the aUas record by using a relative path, the Alias Manager looks at the 
directory at the specified distance above the starting file or directory. Hie Alias Manager 
then constructs a partial pathname by extracting one field of the absolute pathname for 
each step from the target to the common parent. In Figure 4-1, the distance is 2, so the 
partial pathname is "Dictionary:Dict 2". 

Absolute Searches . . 

In contrast to a relative search, ari absolute search always begins at the root directory 
of the file system hierarchy and always descends the hierarchy. The first step m any 
absolute search is to identify the volume on which the target resides. When conducting a 
volume search, the Alias Manager considers the volume's name, its creation date (which 
acts almost as a unique identifier for a volume), and its type (for example, a hard disk, a 
3.5-inch floppy disk, or an AppleShare volume). 
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The Alias Manager first looks for a volume that matches all three criteria: name, creation 
date, and type. The search succeeds if the volume is mbuunted and if its name and 
creation date have not changed since the record was created. If the search fails, the Alias 
Manager attempts to match by creation date and type only. This step locates volumes 
that have been renamed. Finally, the Alias Manager attempts to match by volume name 
and type only. 

If the target is on an unmounted AppleShare volume, the Alias Manager attemptis to 
mount the volume. It presents a name and password dialog box if appropriate. If the 
target is on an ttnmoimted ejectable volume, the Alias Manager displays a dialog box 
prompting the user to insert the volume. Your application can suppress the automatic 
mounting, as explained in the description of the MatchAl ias function on page 4-20. 

Note 

Any time that your application needs to resolve a large number of 
aliases and the resolution of each alias might require user interaction, 
you should ensure that if the user cancels any of the dialog boxes, all 
remaining user interaction is canceled as well. ♦ 

In some circumstances, a relative search identifies the correct target when an absolute 
search cannot. For example, suppose the user of your word-processing application 
creates a working copy of a document and dictionary by copying the entire folder 
Sample to another diski The user later updates the original document and dictionary 
by copying the folder from the working disk. All of the tmderlying file and directory 
identificatior\s change, but the filenames and relative path remain the same. When the 
user later runs the spelling checker on the document, a relative-path search finds the 
correct target dictionary. S 

CO 

Fast Searches 1 



A fast search employs an algorithm designed to find the target of an alias record quickly. 
Depending on how you invoke it, the fast-search algorithm starts with either a relative 
search or an absolute search. The Alias Manager can perform a relative fast search 
whether or not it has identified the target volume, but it cannot perform an absolute fast 
search unless the volume has been identified. 

During an absolute fast search, the Alias Manager first searches by file ID (if the target 
is a file) or directory ID (if the target is a directory). (File IDs and directory IDs are 
described in the chapter "File Manager" in this book.) Even if a file has been renamed 
or moved on a volimie, the Alias Manager can find it quickly through its file ID. 

If the search by file ID or directory ID fails, the Alias Manager searches by name in the 
original parent directory. This search locates the target if its file or directory ID has 
changed but it still exists by the same name in the parent directory (for example, if the 
target was restored from a backup). The Alias Manager compares file numbers of files 
found by name in the correct parent directory. If the file numbers do not match, the file is 
treated as a possible match — that is, it is put on the list of candidates — and the search 
continues. If the target is not foimd by name in the parent directory, the Alias Manager 
looks for a file by file number in the parent directory. A file with the same file number 
but a different name replaces a file with the same name but a different file number in the 
list of matches. 

About the Alias Manager 4-7 
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H the search by file ID or directory ID fails ai^d if the Alias Manager cannot find the 
L;.T;tnIdirectory,itsearcLforthet^^^^^ 

if tS^tar^et resides in the same location on the volume but the duectory © of ^^P^'^* 
di^ory'has changed (for example, if the entire parent directory was restored from 

a backup). 

If the searchby full pathname fails, the AliasManager attempts to find the ffleby tracmg 
pa^afpattaLs up through all parent directories, u^^ 
of directory names. For example, consider this full pathname: 

MyDisk : Fruits : Tropical : Ackees 

If the search by fuU pathname fails. Alias Manager first looks for the partial pathname 
" ^kees^ t^e dirLory with the ID that the directory "MyDisk:Eruits:TropKal had 
wh^^e aUas record w7s cf eated. If that seard. fails, it looks for '.Trop.cal-Ackees m 
the directory with the ID that "MyDiskJ'ruits" had, and so on. 
If you do not a.k for a search by relative path first but do provide a starting Pomt f^^ a 
relative search, and if the aUas record contains relative path mformabon, the Alias 
Cgerperformsarelativesearch after the absolute seaxd..Tl.ereIaUve^^^^ 

succeeds ff the relative path is the same as when the record was created and if the names 
of the target and its intervening parent directories have not changed. 



Exhaustive Searches 



An exhaustive search uses an algorithm that scans an entire volume to look for pos^ble 
matches. The Alias Manager typically performs an exhaushve search by calbng the File 
Manager function PBCat Search, searching for files or directories with a matchmg 
creation date, creator, and type. (See the chapter "File Manager" m this book for a 

description of PBCat Search.) 

n^e PBCatSearch function is available only on volumes that support the HPS routines 
and only on systems running system software version 7.0 and later. When 
PBCatSearch is not available, an exhaustive seardi of the entu:e volume is perfonn«i 
by making a series of indexed File Manager calls, searching for objects with matchmg 
creation date, type, creator, or file number. 



Using the Alias Manager 



You use the Alias Manager primarily to create and resolveaUas records. You can also use 
it to get information about and update alias records. 

The AUas Manager creates an alias record in memory and provides you with a han^e to 
the record. When you no longer need a record in memory, free the memory by caUmg die 
Memory Manager'sDisposeHandleprocedure. Whenever possible, you should store 

and retrieve alias records as resources of type ' al i s * . 



4-8 



Using the Alias Manager 



TIVO-408830 



CHAPTER 4 



Alias Manager 

,/ 

Alias Manager functions accept and return file specifications in the form of FSSpec 
records, which contain a volimie reference number, a parent directory ID, and a 
target name. See the chapter 'Tile Manager" in this book for a description of file 
identification conventions. 

Before calling any of the Alias Manager functions, you should verify that the 
Alias Manager is available by calling the Gestalt function with a selector of 
gestaltAliasMgrAttr. If Gestalt sets the gestaltAliasMgrPresent 
bit in the response parameter, the Alias Manager is present. 

For more detailed descriptions of the functions described in this section, see "Alias 
Manager Reference" beginning on page 4-13. 

Creating Alias Records 

You create a new alias record by calling one of three functions: NewAlias, 
NewAliasMinimal, or NewAliasMinimalFromFullPath. The NewAlias function 
creates a complete alias record that can make full use of the alias-resolution algorithms. 
The other two functions are streamlined variations designed for circumstances when 
speed is more important than robust resolution services. All three functions allocate the 
memory for the record, fill it in, and return a handle to it. 

The NewAl ias function always records the name and the file or directory ID of the 
target, its creation date, the parent directory name and ID, and the voliune name and 
creation date. It also records the full pathname of the target and a collection of other 
information. You can have NewAlias store relative path information as well by 
supplying a starting point for a relative path (see "Relative Searches" on page 4-5 for a 
description of relative paths). 

Call NewAl ias when you want to create an alias record to store for later use. For 
example, suppose you are writing a word-processing application that allows the user to 
customize a dictionary for use with a single text file. Your application stores the custom 
data in a separate dictionary file Ln the same directory as the document. As soon as you 
create the dictionary file, you can call NewAlias to create an alias record for that file, 
including path information relative to the user's text file. Listing 4-1 shows how to use 
NewAlias to create a new alias. 

Listing 4-1 Creating an alias record 



FUNCTION DoCreateAlias (myDoc, inyDict: FSSpec): OSErr; 
VAR 

myAliasHdl: AliasHandle; {handle to created alias) 

myErr : OSErr; 
BEGIN 

myErr := NewAlias (@myDoc, myDict, myAliasHdl); {create alias record} 
IF myAliasHdl <> NIL THEN 

myErr := DoSaveAlias (myDoc, myAliasHdl); {save it as a resource) 

DoCreateAlias := myErr; {return result code) 

END; 

Using the Alias Manager ^ ^ 
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The function DoCreateAlias defined in Usting 4-1 takes two FSSpec records as 
parameters. The first specifies the document that is to serve as the starting point for a 
relative search, in this case the user's text file. The second FSSpec record specifies the 
target of the alias to be created, in this example the dictionary fUe. The DoCreateAlias 
function caUs NewAlias to create the alias record; if successhil, it calls the appUcation- 
defined function DoSaveAlias to save the alias record as a resource in the document 
file's resource fork. See Listing 4-2 on page 4-12 for a definition of DoSaveAlias. 
The two variations on the NewAlias function, NewAliasMinimal and 
NewAliasMinimalFromFullPath, record only a minimum of information about 
the target. The NewAliasMinimal function records only the target's name, parent 
directory ID, volume name and creation date, and volume mounting information. The 
NewAliasMinimalFromFullPath function records only the full pathname of the 
target, including the volume name. 

Use NewAliasMinimal or NewAliasMinimalFromFullPath when you are willing 
to give up robust alias-resolution service in return for speed. The Finder, for example, 
stores minimal aUases in the Apple events that tell your application to open or print a 
document. Because the alias record is resolved ahnost immediately, the description is 
likely to remaia valid, and the shorter record is probably safe. 

You can use NewAliasMinimalFromFullPath to create an alias record for a target 
that doesri't exist or that resides on an unmounted volume. 

Res olving Alias Records . 

The Alias Manager provides two functions that you can use to resolve alias records: 

■ the high-level function ResolveAl ias, which performs a fast search and identifies 
only one target 

■ the low-level function Mat chAl ias, which can perform a fast search, an exhaustive 
search, or both and which can return a list of target candidates 

In general, when you want to identify only the single most likely target of an alias 
record, you call ResolveAlias. You call MatchAlias when you want your program 
to control the search. 

Identifying a Single Target 

To resolve an alias record, you usually call the ResolveAlias function. This function 
performs a fast search (described earlier in "Fast Searches" on page 4-7) and exits after it 
identifies one target. The ResolveAlias function compares some key ii\formation 
about the identified target with the ii\formation stored in the; alias record. If any of the 
information is different, ResolveAl i as automatically updates the record. 

Note 

Like all other Alias Manager functions, ResolveAlias updates the 
record only in memory. Yotu: application is responsible for updating 
alias records stored on disk when appropriate. ♦ 
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In the dictionary example illustrated in Figure 4-1 on page 4-6, the application calls 
ResolveAlias with a relative path specification when the user runs the spelling 
checker on a document with a customized dictionary. If you provide a relative starting 
point, ResolveAlias performs the relative search first. 

The ResolveAlias function reports, in the wasChanged parameter, whether it 
updated the alias record. After ResolveAlias runs, the value of wasChanged is TRUE 
if the record was updated and FALSE if it was not. If you are storing the alias record, 
check the value of v/asChanged (as well as the function's result code) to see whether to 
update the stored record after resolving an alias. 

If ResolveAl ias can't resolve the alias record, it rettims a nonzero result code. A result 
code of f nf Err signals that ResolveAlias has found the correct voltime and parent 
directory but not the target file or folder In this case, ResolveAlias constructs a valid 
FSSpec record that describes the target. You can use this record to explore possible 
solutions to the resolution failure. You can, for example, pass the FSSpec record to the 
File Manager fxmction FSpCreate to create a replacement for a missing file. 

Identifying Multiple Targets 

The MatchAl ias function is a low-level routine that gives yotu* application control over 
the search algorithms. 

You can control 

■ whether to attempt an automatic mounting of unmovmted volimnes 

■ whether to search on more than one volume 

■ whether to perform a fast search, an exhaustive search, or both 

■ what the order of the absolute and relative searches in a fast search should be 

■ whether to pursue search strategies that require interaction with the user (such as 
asking for a password while mounting an AppleShare voltune) 

You can also specify a maximum nxmiber of candidates that MatchAl ias can identify. 
For details about controlling a search with the MatchAl ias function, see its description . 
beginning on page 4-20. 

You can supply an optional filter function that Mat chAl ias calls 

■ each time it identifies a possible match 

■ when three seconds have elapsed without a match 

The filter function determines whether each candidate is added to the list of possible 
targets. It can also terminate the search. See "Filtering Possible Targets" on page 4-25 
for a description of the filter function. 

The MatchAl ias function returrxs, in an array of file system specification records, all 
candidates that it identifies. 
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Maintaining Alias Records 

You can store alias records as resources of type ' al is ' . 
CONST 

rAliasType = ■ alis ■; (resource type for saved alias records) 

To store and retrieve resources, use the star^dard Resource Manager functions 
(AddResource GetResource, and GetNaiaedResource) descnbed in the chapter 

one way to save an aUas record as a resource in a document &le s resource fork. 



Listing 4-2 Storing an alias record as a resource 



FUNCTION DoSaveAlias (wDoc: FSSpec; i«yAliasHdl: AliasHandle) : OSErr; 
VAR 

™me,°i"aU, Ulle «f ■o-t.r of accun.e„f3 resource £or« 

CONST 

kID =129; 

kName = 'Dictionary Alias'; 
BEGIN 

myFile := FSpOpenResFile (myDoc, f sCurPerm) ; 

xnyFile = -1 THEN (couldn't open the document's resource fork] 

BEGIN 

DoSaveAlias := ResError; 
exit (DoSaveAlias) ; 
END; 

AddResource (Handle (myAliasHdl), rAliasType, kID, kName); 
n^Err := ResError; (check for errors adding resource) 

IF my Err = noErr THEN 
BEGIN 

WriteResource (Handle (myAliasHdl) ) ; 

inyErr := ResError; (check for errors writing resource) 
END; 

DoSaveAlias := myErr; 
END; 

Note that DoSaveAl i as assumes that the file specified by the myDoc parameter already 
has a resource fork and that the file is not yet open. Your application might have 
different requirements. 

To update an alias record, use the UpdateAl ias fimction. You typicallycall 

updat eAl i as any time you know that the target of an alias record has been reamed 

or otherwise changed. You are most likely to call Updat eAlias after a caU to the 
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MatchAl ias function. If MatchAlias identifies a single target, it sets a flag telling 
you whether or not the key information about the target file matches the information in 
the alias record. It is the responsibility of your application to update the record. 

The ResolveAlias function automatically updates an alias record if any of the key 
information about the identified target does not match the ir\formation in the record. 

Getting Information From Alias Records 

To retrieve information from an alias record without actually resolving the record, call 
the GetAliasInfo function. You can use GetAliasInf o to retrieve the name of the 
target, the names of the target's parent directories, the name of the target's volume, or, in 
the case of an AppleShare voliime, its zone or server name. 

The information returned by GetAliasInfo might be stale. GetAliasInfo reads the 
information stored in the alias record, which might have changed since the creation of 
the record. Because it doesn't resolve the alias record, GetAliasInfo is most useful for 
providing information quickly. 

Customizing Alias Records 

An alias record contains two kinds of information: public information available to your 
application and private information available only to the Alias Manager. Your 
application can use the first field, userType, to store its own signature or any other data 
that fits info 4 bytes. Your application can use the second field, aliasSize, to customize 
the alias record for storing additional data. 

The Alias Manager stores, in the aliasSize field, the size of the record at the time it is 
created or updated. To customize an alias record, you first use the Memory Manager's 
SetHandleSize procedure to increase the size of the record. You can then find the 
starting address of your own data in the record by adding the record's starting address 
to the length recorded in the aliasSize field. If you use the Memory Manager to 
expand the record, the Alias Manager preserves your data, even if it changes the size of 
its own data when updating the record. 

Note 

In general, you should customize only alias records that you 
have created. ♦ 



Alias Manage r Reference 

This section describes the routines provided by the Alias Manager and the 
AliasRecord data structiue you must pass when caDing those routines. 
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Data Str uctures 

' The Alias Manager uses alias records to store information that allows it to locate an 

object in the file system. 

Alias Records " 

Alias records are defined by the AliasRecord data type. 

TYPE AliasRecord = 
RECORD 

userType: OSType; {application's signature} 

aliasSize: Integer; . {size of record when created) 

{variable-length private data) 
END; 

Field descriptions 

userType A 4-byte field that can contain application-specific data. When an 

alias record is created, this field contains 0. Your application can use 
this field for its own purposes. Typically you should store your 
application's signature here. 

aliasSize The size, in bytes, assigned to the aUas record at the time of its 

creation or updating. This is the total size of the record, including 
the userType and aliasSize fields, as well as the variable-length 
data that is private to the Alias Manager. 

Following these two fields is a variable-length block of data maintained privately by the 

Alias Manager. 



Alias Manager Ro utines 

This section describes the routines you use to create, update, resolve, and read alias 
records. Alias Manager routines use file system specification records (defined by the 
FSSpec data type) to identify files, directories, and volumes. To create an FSSpec 
record, call the function FSMakeFSSpec, described in the chapter "File Manager" in 
this book. 

The Alias Manager routines can return the result codes listed in this section or any other 
applicable file system or memory management result codes. 



Creating and Updating Alias Records 

You can use the functions NewAlias, NewAliasMinimal, 
NewAliasMinimalFromFullPath, and UpdateAlias to create and 
update alias records. 
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New Alias 



You use the NewAlias function to create a complete alias record. 

FUNCTION NewAlias {fromFile: FSSpecPtr; target: FSSpec; 

VAR alias: AliasHandle) : OSErr; 

f romFi le The starting point for a relative path, to be used later in a relative search. 
If you do not need relative path information in the record, pass a 
fromFile value of NIL. If you want NewAlias to record relative path 
information, pass a pointer to a valid FSSpec record in this parameter. 
The two files or directories, fromFile and target, must reside on the 
same volume. 

target An FSSpec record for the target of the alias record. 

alias Ahandle to the newly created alias record. If the function fails to create 

an alias record, it sets al ias to NIL. 



DESCRIPTION 

The NewAlias function creates an alias record that describes the specified target. It 
allocates the storage, fills in the record, and puts a record handle to that storage in the 
alias parameter. NewAlias always records the name and file or directory ID of the 
target, its creation date, the parent directory name and ID, and the volume name and 
creation date. It also records the full pathname of the target and a collection of other 
ir\formation relevant to locating the target, verifying the target, and mounting the 
target's volume, if necessary. You can have NewAl ias store relative path information as S 
well by supplying a starting point for a relative path (see "Relative Searches" on page 4-5 g 
for a description of relative paths). o 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for NewAlias are 
Trap macro Sfelector 

_AliasDispatch $0002 



RESULT CODE 

noErr 0 No error 
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NewAliasMinimal 



You use the NewAl iasMinimal function to create a short ahas record quickly. 

FUNCTION NewAliasMinimal (target: FSSpec; 

VAR alias; AliasHandle) : OSErr; 

target An FSSpec record for the target of the aUas record, 
alias Ahandle to the newly created alias record. If the function fails to create 

an alias record, it sets alias to NIL. 



DESCRimON 

The NewAliasMinimal function creates an alias record that contains only the minunum 
information necessary to describe the target: the target name, the parent directory ID, the 
volume name and creation date, and the volume mounting information. The 
NewAliasMinimal hmction uses the standard alias record data structure, but it fills m 
only parts of the record. 

Note 

The ResolveAl ias function, described on page 4-19, never updates a 
minimal alias record. ♦ 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for NewAliasMinimal are 

Trap macro Selector 

_A1 i a sDi spa t ch $0008 



RESULT CODES 

noErr 0 No error ru • 

paramErr -50 The value of target or alias parameter, or of both, is 

NIL, or the alias record is corrupt 
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You use the function NewAliasMinimalFromFuUPath to quickly create an alias 
record that contains only the full pathname of the target. 

FUNCTION NewAliasMinimalFromFullPath 

(fullPathLength: Integer; fullPath: Ptr; 
zoneName: Str32; serverName: Str31; 
VAR alias: AliasHandle) : OSErr; 

fullPathLength 

The number of characters in the full pathname of the target. 

fullPath Apointer to a buffer that contains the full pathname of the target. The full 
pathname starts with the name of the volume, includes all of the directory 
names in the path to the target, and ends with the target name. (For a 
description of pathnames, see the chapter "File Manager" in this book.) 

zoneName The AppleTalk zone name of the AppleShare voltmie on which the target 
resides. Set this parameter to a null string if you do not need it. 

serverName The AppleTalk server name of the AppleShare volume on which the 
target resides. Set this parameter to a null string if you do not need it. 

alias A handle to the newly created alias record. If the function fails to create 

an alias record, it sets alias to NIL. 



DESCRIFHON 

The NewAliasMinimalFromFuUPath fimction creates an alias record that identifies 
the target by full pathname. You can call NewAliasMinimalFromFuUPath to create 
an alias record for a file that doesn't exist or that resides on an immounted volume. 

The NewAliasMinimalFromFuUPath fimction uses the standard alias record data 
structure, but it fills in only the information provided in the input parameters. You can 
therefore use NewAliasMinimalFromFuUPath to create ahas records for targets on 
unmounted volumes. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for NewAl iasMinimalFromFull Path are 

Trap macro Selector 

__AliasDispatch $0009 



RESULT CODES 

noErr 0 No error 

paramErr -50 Parameter error 
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You use the UpdateAlias function to update an alias record. 

FUNCTION UpdateAlias (fromFile: FSSpecPtr; target: FSSpec; 

alias: AliasHandle; 

VAR wasChanged: Boolean) : OSErr; 

in this parameter. 

target The target of the alias record. This parameter must be a valid 

FSSpec record, 
alias Ahandle to the alias record to be updated. 

— — .--^^^^^ 

one UpdateAlias sets the wasChanged parameter to FALSE. 
Sh'emJeJt sets it to TRUE. Check this parameter to determme whether 
you need to save an updated record. 



DESCRimON 



The UpdateAlias function updates the alias record pomted -•'^ '^^^^^^^^^^ 
so that it describes the target specified by the target parameter. The UpdateAlias 
function rebuads the entife alias record and fills it in as the NewAlias function would. 
The UpdateAlias function always creates a complete alias record. When you use 
UpdateAl ias to update a minimal alias record, you convert the mmimal record to a 
complete record. 



SPEOAL CONSIDERATIONS 

The two files or directories, fromFile and target, must reside on the same volume. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for UpdateAl ias are 

Trap macro Selector 

AliasDispatch $0006 



RESULT CODES 



noErr 
paramErr 



0 No error ^ ^^u^*k 

-50 The value of the target or alias parameter, or both, 
is NIL, or the ahas record is corrupt 
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Resolving and Reading Alias Records 

You can use the functions ResolveAlias and Match Alias to resolve or find possible 
targets of an alias record. You can use the function GetAliasInf o to get information 
about the target of an alias without actually resolving the alias. 



ResolveAlias 



You use the ResolveAl ias function to identify the single most likely target of an 
alias record. 

FUNCTIOl^ ResolveAlias (fromFile: FSSpecPtr; alias: AliasHandle; 

VAR target: FSSpec; 
VAR wasChanged: Boolean) : OSErr; 

f roiTiFi le The starting point for a relative search. If you pass a f romFi le parameter 
of NIL, ResolveAl ias performs only an absolute search. If you pass 
a pointer to a valid FSSpec record in the fromFile parameter, 
ResolveAlias performs a relative search for the target, followed by 
an absolute search only if the relative search faOs. If you want to perform 
an absolute search followed by a relative search, you must use the 
MatchAlias function. 

alias Ahandle to the alias record to be resolved and, if necessary, updated. 

target The target of the alias record. This parameter must be a valid 
FSSpec record. 

wasChanged A Boolean value indicating whether the alias record to be resolved was 

updated because it contained some outdated information about the target. 



DESCRIPTION 

The ResolveAlias function performs a fast search for the target of the alias, as 
described in "Fast Searches" on page 4-7. If the resolution is successful, ResolveAlias 
returns (in the target parameter) the FSSpec record for the target file system object, 
updates the alias record if necessary, and reports (through the wasChanged parameter) 
whether the record was updated. If the target is on an ujnmoimted AppleShare volimie, 
ResolveAlias automatically moimts the volume. If the target is on an immotmted 
ejectable volume, ResolveAl i a s asks the user to insert the volimie. The 
ResolveAlias function exits after it finds one acceptable target. 

After it identifies a target, ResolveAl ias compares some key information about the 
target with the informiation in the alias record. (The description of the MatchAlias 
function, beginning on page 4-20, lists the key information.) If the information differs, 
ResolveAlias updates the record to match the target. If it updates the alias 
record, ResolveAl ias sets the wasChanged parameter to TRUE. Otherwise, it sets 
it to FALSE. (ResolveAlias never updates a minimal alias, so it never sets 
wasChanged to TRUE when resolving a minimal alias.) 
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men it finds the specified volume and parent directory but fails to fm^ 

directory in that location, ResolveAlias rehams a result code of f nf Err and hlk m 

STtar^et parameter with a complete FSSpec record descnbmg the targe (*at .s, the 

volume reference number, parent directory ID, and fUename or folder name . The 

F Src^cS is valid, alLugh the object it describes does not exist. Tlus mf ormation 

Srdi:faW''thatlets%u explore possiW^ 

You can, for example, pass the FSSpec record to the Fde Manager function FSpCreate 
to create a replacement for a missing file. 

ll.e ResolveAlias function displays the standard dialog boxes when '^^^^^^^V^ 
from the user, such as a name and password for mounhng a remote volume. The user 
can cancel the resolution through these dialog boxes. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for ResolveAlias are 

Selector 



Trap macro 

AliasDispatch 



$0003 



RESULT CODES 



noErr 
nsvErr 
fnfErr 
paramErr 

dirNFErr 
usrCanceledErr 



0 No error 

-35 The volume is not mounted 

-43 Tareet not found, but volume and parent directory found 

-50 The value of the target or alias parameter, or both, is 
NIL, or the alias record is corrupt 

-120 Parent directory not foimd 

-128 The user canceled the operation 



MatchAlias 



You use the MatchAl ias function to identify a list of possible matches and V^^^^^J^^ 
through an optional selection filter. Tlie filter can rehim more than one possible match. 

FUNCTION MatchAlias (fromFile: FSSpecPtr; rulesMask: Longlnt; 

alias: AliasHandle; VAR aliasCount: Integer ; 
aliasList: FSSpecArrayPtr; 
VAR needsUpdate: Boolean; 
aliasFilter : AliasFilterProcPtr ; 
yourDataPtr: UNIV Ptr) : OSErr; 

f romFile The starting point for a relative search. If you do not want MatchAlias 
toperformarelativesearch,set fromFile to NIL. If you want 
MatchAlias to perform a relative search, pass a pointer to a file system 
specification record that describes the starting point for the search. 

rul esMask A set of rules to guide the resolution. Pass the sum of aU of the rules you 
want to invoke. 
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alias A handle to the alias record to be resolved . 

aliasCount On input, the maximum ntmiber of possible matches to return. On output, 
the actual nimiber of matches returned. 

aliasLi St A poiiiter to the array that holds the results of the search. 

needsUpdate 

A Boolean flag that indicates whether the alias record to be resolved needs 
to be updated. 

aliasFilter 

An application-defined filter function. 

yourDataPtr 

A pointer to data to be passed to the filter function. 

DESCRIPTION 

The MatchAlias function resolves the alias record specified by the alias parameter, 
follov^ing the rules specified by the rulesMask parameter. Then it returns, in the 
structure specified by the aliasList parameter, a list of possible candidates. The 
MatchAlias function places, in the aliasCount parameter, the number of 
candidates identified. 

You specify the matching criteria by passing a sum of these constants in the 
rulesMask parameter. 

CONST 

kARMMountVol 
kARMNoUI 
kARMMultVols 
kARMSearch 
kARMSearchMore 
kARMSearchRelFirst 

Constant descriptions 

kARMMountVol Automatically try to mount the target's volume if it is not 
mounted. 

kARMNoUI Stop if a search requires user interaction, such as a password dialog 

box when moimting a remote volttme. If user interaction is needed 
and kARMNoUI is in effect, the search fails. 

kARMMu 1 1 Vo 1 s Search all mounted volimies. The search begirw with the volume on 
which the target resided when the record was created. When you 
specify a fast search of all moimted volumes. Mat chAl ias f>erfonns 
a formal fast search only on the volume described in the alias record. 
On all other volimies it looks for the target by ID or by name in the 
directory with the specified parent directory ID. When you specify 
an exhaustive search of multiple volxames. Ma t chAl ias performs 
the same search on all voliunes. When resolving ari alias record 
created by NewAliasMinimalFromFullPath, MatchAlias 
ignores this flag. 



$00000001; {moimt volume automatically) 

$00000002; {suppress user interface) w 

$00000008; {search on multiple volumes) » 

$00000100; {do a fast search) . ^ 

$00000200; {do an exhaustive search) ^ 
$00000400; {do a relative search first) 
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kARMSearch Perform a fast search for the alias target. If kARMSearchRelFirst 

is not set, perform an absolute search first, followed by a relative 
search only if the value of.the f romFile parameter is not NIL and 
the list of matches is not full. 

kARMSearchMore Perform an exhaustive search for the alias target. On HPS volumes, 
the exhaustive search uses the Pile Manager function PBCat Search 
to identify candidates with matching creation date, type, and creator. 
The PBCatSearch function is available only on HPS volumes and 
only on systems running version 7.0 or later. On MPS volumes or 
HPS volumes that do not support PBCatSearch, the exhaustive 
search makes a series of indexed calls to File Manager functions, 
using the same search criteria. If you set kARMSearchMore and 
either or both of kARMSearch and kARMSearchRelFirst, 
MatchAl ias performs the fast search first. 

kARMSearchRelFirst 

If kARMSearch is also set, perform a relative search before the 
absolute search. (If kARMSearch is also set and the target is found 
through the absolute search, MatchAlias sets the needsUpdate 
flag to TRUE.) If neither kARMSearch nor kARMSearchMore is set, 
perform only a relative search. If kARMSearch is not set but 
kARMSearchMore is set, perform a relative search followed by an 
exhaustive search. 

You must specify at least one of the last three parameters: kARMSearch, 

kARMSearchMore, and kARMSearchRelFirst. 

Your application can specify a maximum number of possible matches by setting the 
aliasCount parameter. MatchAlias changes the al iasCount parameter to the 
actual number of candidates identified. If Mat chAl ias finds the parent directory on the 
correct volume but does not find the target, it sets the al iasCount parameter to 1, puts 
the file system specification record for the target in the results list, and returns f nf Err. 
The FSSpec record is valid, although the object it describes does not exist. This 
information is intended as a "hint" that lets you explore possible solutions to the 
resolution failure. You can, for example, use the FSSpec record and the Pile Manager 
function FSpCreate to create a replacement for a missing file. 

The needsUpdate flag is a signal to your application that the record might need to be 
updated. After it identifies a target, MatchAlias compares some key information about 
the target with the same information in the record. If the information does not match, 
MatchAlias sets the needsUpdate flag to TRUE. The key iiiformation is 

■ the name of the target 

■ the directory ID of the target's parent 

■ the file ID or directory ID of the target 

■ the name and creation date of the volume on which the target resides 

The MatchAl ias function also sets the needsUpdat e flag to TRUE if it identifies a list of 
possible matches rather than a single match or if kARMSearchRelFirst is set but the 
target is identified through either an absolute search or an exhaustive search. Otherwise, 
the MatchAlias function sets the needsUpdate flag to FALSE. MatchAlias always 
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sets the needsUpdate flag to FALSE when resolving an alias created by 
NewAliasMinimal. If you want to update the alias record to reflect the final 
results of the resolution, call UpdateAlias. 

The aliasFil ter parameter points to a filter function supplied by yoiu: application. 
The Alias Manager executes this function each time it identifies a possible match and 
after the search has continued for three seconds without a match. Your filter function 
returns a Boolean value that determines whether the possible match is discarded (TRUE) 
or added to the list of possible targets (FALSE). It can also terminate the search by setting 
the variable parameter quit Flag. See "Filtering Possible Targets" on page 4-25 for a 
description of the filter function. 

The yourDataPtr parameter can point to any data that your application might need in 
the filter function. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for MatchAlias are 
Trap macro Selector 

_AliasDispatch $0005 



RESULT CODES 



noErr 


0 


No error 


nsvErr 


-35 


The volume is not moimted 


fnfErr 


-43 


Target not foimd, but volume and parent directory found 


paramErr 


-50 


The value of the target or alias parameter, or both, is 






NIL, or the alias record is corrupt 


u s rCance 1 edEr r 


-128 


The user canceled the operation 




K 

0 
(Q 



GetAliasInfo 



You use the GetAliasInfo function to get iitformation from an alias record without 
actually resolving the record. 

FUNCTION GetAliasInfo (alias: AliasHandle; index: Aliasinf oType; 

VAR theString: Str63) : OSErr; 

alias A handle to the alias record to be read . 

index The kind of information to be retrieved. 

theSt r ing A String that holds the requested information. 



DESCRimON 



The GetAliasInfo function retrieves the information specified by the index 
parameter from the record pointed to by the alias parameter and places that 
information in the parameter theString. 
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The index parameter specifies the kind of information to be retrieved. If the value of 
index is a positive integer. Get Al iasinf o retrieves the parent directory ^ has 
same hierarchical level above the target as the index parameter (for example, an xndex 
value of 2 rehims the name of the parent directory of the target's parent directory). You 
can therefore assemble the names of the target and all of its parent directones by making 
repeated calls to Get Al iasinf o with incrementing index values, starting with a value 
of 0. When the value of index is greater than the number of levels between the target 
and the root, GetAliasInf o returns an empty string. You can also set the index 
parameter to one of the following five values: 



CONST 

asiZoneName 
asiServerName 
as iVolumeName 
asiAliasName 
a s i Par en tName 



_3; {get zone name} 

_2; {get server name) 

-1; {get volume name] 

0; {get target name) 

1; {get parent directory name) 



Constant descriptions 



asiZoneName 

asiServerName 

a s i Vo lumeName 
asiAliasName 
asiParen tName 



If the record represents a target on an AppleShare volume, retrieve 
the server's zone name. Otherwise, rehim an empty stnng. 
If the record represents a target on an AppleShare volume, retrieve 
the server name. Otherwise, return an empty string. 
Return the name of the volume on which the target resides. 
Return the name of the target. 

Return the name of the parent directory of the target of the record. If 
the target is a volume, return the volume name. 
Ihe GetAliasInf o hmction returns the information stored in the aUas record, which 
might not be current To ensure that the information is current, you can resolve and 
update the alias record before calling Get Al iasinf o. 

Note 

The GetAliasInf o function cannot provide all kinds of information 
about a miiumal alias. ♦ 



ASSEMBty-LANGUAGE INFORMATION 

The trap macro and routine selector for GetAliasInf o are 
Trap macro Selector 

_AliasDispatch $0007 



RESULT CODES 



noErr 
paramErr 



0 No error 

-50 The value of alias or theString parameter, or botn, 
is NIL; the value of index is less than the value of 
asiZoneName; or the alias record is corrupt 
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Application-Defined Routines 

The Alias Manager supports a single application-defined routine, a function for filtering 
out possible targets of an alias record. 

Filtering Possible Targets 

You can write your own filter function to examine possible targets identified by the . 
MatchAl ias function. The MatchAlias function calls your filter function each time it 
identifies a possible match or when three seconds have elapsed without a match. 



MyMatchAliasFilter 



You can pass the address of an alias-matching filter function to the MatchAlias 
function. 

FUNCTION MyMatchAliasFilter (cpbPtr: CInfoPBPtr; 

VAR quitFlag: Boolean; 
myDataPtr: Ptr) : Boolean; 

cpbP t r A pointer to a catalog information parameter block. 

qui t F 1 ag On exit, set this to TRUE if you want to terminate the search. 

myDataPtr A pointer to custom data. 



DESCRIPTION 

Your application-defined filter function is called by MatchAlias to filter out possible 
matches. When your function is called, the cpbPtr parameter points to the catalog 
information parameter block of the possible match (returned by the File Manager 
function PBGetCatInf o). The MatchAlias function sets this parameter to NIL if it 
is calling your function to give it the periodic chance to terminate the search. (Do not 
use this pointer without checking for NIL.) If you want to terminate the search, set the 
quitFlag parameter to TRUE. 

The nr/DataPtr parameter points to any customized data that your application passed 
when it caUed MatchAlias. This parameter allows yotir filter function to access any 
data that your application has set up on its own. 

Your function should retvun TRUE to indicate that the possible match is to be discarded, 
or FALSE to indicate that the possible match is to be added to the list of possible targets. 
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SuiiuBary of the Alias Manager 



Pascal Summary 



Constants 



CONST 

{Gestalt constants} 
gestaltAliasMgrAttr 
gestaltAliasMgrPresent 



•alls*; {Alias Mgr attributes selector} 

0; {Alias Mgr is present} 



(resource type for saved alias records} 
rAliasType = *alis'; 

{masks for alias resolution action rules used by MatchAlias} 



kARMMountVol 

kARMNoUI 

kARMMultVols 

kARMSearch 

kARMSearchMore 

kARMSearchRelFirst 



$00000001 
$00000002 
$00000008 
$00000100 
$00000200 
$00000400 



{mount volume automatically} 
(suppress user interface) 
(search on multiple volumes} 
(do a fast search} 
(do an exhaustive search} 
(do a relative search first} 



(index values for GetAliasInf o} 



asiZoneName 
asiServerName 
a s i VolumeName 
asiAliasName 
as iParentName 



-3? 

-2; 

-1; 

0; 

1; 



(get zone name} 

{get server name) 

(get volume name) 

(get target name) 

(get parent directory name) 



Datatypes 



TYPE AliasRecord 
RECORD 

userType: OSType; 
aliasSize : Integer ; 
(variable-length private data) 
END; 



{alias record} 

(application's signature} 
(size of record when created) 
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AliasPtr 
AliasHandle 



''AliasRecord; 
'^AliasPtr; 



Aliasinf oType 
AliasFilterProcPtr 



Integer; {alias record information type) 
ProcPtr; {application-defined routine) 



Alias Manager Routines 



Creating and Updating Alias Records 



FUNCTION NewAlias 



(fromFile: FSSpecPtr; target: FSSpec; 
VAR alias: AliasHandle) : OSErr; 



FUNCTION NewAliasMinimal (target: FSSpec; 

VAR alias: AliasHandle): OSErr; 

FUNCTION NewAliasMinimalFromFullPath 

(fullPathLength: Integer; fullPath: Ptr; 
zoneName: Str32; ■ serve rNaxne : Str31; 
VAR alias: AliasHandle): OSErr; 

FUNCTION UpdateAlias (fromFile: FSSpecPtr; target: FSSpec; 

alias: AliasHandle; 

VAR wasChanged: Boolean) : OSErr; 



Resolving and Reading Alias Records 



FUNCTION ResolveAlias 



FUNCTION MatchAlias 



FUNCTION GetAliasInfo 



(fromFile: FSSpecPtr; alias: AliasHandle; ' 

VAR target: FSSpec; 

VAR wasChanged: Boolean) : OSErr; 
(fromFile: FSSpecPtr; rulesMask: LongInt; 

alias: AliasHandle; VAR aliasCount: Integer; 

aliasList : FSSpecArrayPtr ; 

VAR needsUpdate.: Boolean; 

aliasFilter : AliasFilterProcPtr; 

yourDataPtr: UNIV Ptr): OSErr; 
(alias: AliasHandle; index: Alias InfoType; 

VAR theString: Str63) : OSErr; 



I 



IB 

to 

<D 



Application-Defined Routine 



FUNCTION MyMatchAliasFilter (cpbPtr: CInfoPBPtr; VAR quitFla^: Boolean; 

myDataPtr: Ptr): Boolean; 
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C Surhmary 



Constants 



/*Gestalt constants*/ 
#define gestaltAliasMgrAttr 'alis* 
#define gestaltAliasMgrPresent 0 

/♦resource type for saved alias records*/ 
ttdefine rAliasType 'alis* 

/♦masks for alias resolution action rules 
enum {kARMMountVol = 0x00000001} 

enum {kARMNoUI = 0x00000002} 

enum {kARMMultVols = 0x00000008} 

enum {kARl^Searcti = 0x00000100} 

enum {kARMSearchMore , = 0x00000200} 
enum (kARMSearchRelFirt = 0x00000400} 



/*Alias Mgr attributes selector*/ 
/*Alias Mgr is present*/ 



used by MatchAlias*/ 

/*mount volume automatically*/ 

/♦suppress user interface*/ 

/*search on multiple volumes*/ 

/*do a fast search*/ 

/*do an exhaustive search*/ 

/*do a relative search first*/ 



/*index values for GetAliasInf o* / 
enum {asiZoneName = -3} 

en\ira (asiServerName = -2} 
enum {asiVolumeName = -1} 
enum {asiAliasName = 0}; 

enum {asiParentName = 1}; 



/*get zone name*/ 

/*get server name*/ 

/*get volume name*/ 

/*get target name*/ 

/*get parent directory name*/ 



Data Types 



typedef struct { 
OSType 

unsigned short 
} AliasRecord; 



userType; 
aliasSize; 



/*alias record*/ 
/♦application's signature*/ 
/*size of record when created*/ 



typedef AliasRecord *AliasPtr; 
typedef AliasRecord **AliasHandle; 
typedef short AliasInfoType; 



/*alias record information type*/ 



typedef pascal Boolean (*AliasFilterProcPtr) (CInfoPBPtr cpbPtr, 

Boolean *quitFlag, Ptr yourDataPtr) ; 
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Alias Manager Routines 



Creating and Updating Alias Records 

pascal OSErr NewAlias (const FSSpec *froinFile, const FSSpec *target, 

AliasHandle *alias) ; 
pascal OSErr NewAliasMinimal (const FSSpec *target, AliasHandle *alias) ; 
pascal OSErr NewAliasMinimalFromFullPath 

(short fullPathLength, 

const unsigned char *fullpath, 

const Str32 zoneName, const Str31 serverName, 

AliasHandle *alias) ; 

pascal OSErr UpdateAlias (const FSSpec *froinFile, const FSSpec *target, 

AliasHandle alias. Boolean *wasChanged) ; 

Resolving and Reading Alias Records 

pascal OSErr ResolveAlias (const FSSpec *fromFile, AliasHandle alias, 

FSSpec *target. Boolean *wasChanged) ; 

pascal OSErr MatchAlias (const FSSpec *fromFile, 

unsigned long rulesMask, 

const AliasHandle alias, short *aliasCount, 
FSSpecPtr aliasList, Boolean *needsUpdate, 
AliasFilterProcPtr aliasFilter, 
Ptr yourDataPtr) ; 

pascal OSErr GetAliasInfo (const AliasHandle alias, Aliasinf oType index, 

Str63 theString) ; 

Ap plication-Defined Routine 

pascal Boolean MyMatchAliasFilter 

(ClnfoPBPtr cpbPtr, Boolean *quitFlag, 
Ptr myDataPtr) ; 



Assembly-Language Summary 



Data Structure 



Alias Record Data Structure 

0 userType long file type of target file 

4 aliasSize word size, in by tes, of record 
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TYapJjtec^ 

Trap Macro Requiring Routine Selectors 

_AliasDispatch 



Selector 


Routine 


$0002 


NewAlias 


$0003 


ResolveAlias 


$0005 


MatchAlias 


$0006 


UpdateAlias 


$0007 


GetAliasInfo 


$0008 


NewAliasMinimal 


$0009 


NewAliasMinimalFromFullPath 


$000C 


ResolveAliasFile 



Result Codes 



noErr 0 

nsvErr -35 

fnfErr ^3 

paramErr -50 

dirNFErr -120 

usrCanceledErr -128 



No error 

The volume is not mounted 

Target not found, but voliune and parent directory found 

Parameter error 

Parent directory not found 

The user canceled the operation 
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This chapter describes the Disk Initialization Manager, the part of the Operating System 
that allows you to initialize disks and erase the contents of previously initialized disks. 
The Disk Initialization Manager provides a routine that allows you to present the 
standard user interface for irutializing and naming disks. It also provides routines that 
allow you to initialize disks without presenting that standard user interface. 

You need to read this chapter if your application does not mask out disk-inserted events. 
When your application receives a disk-inserted event, it must determine whether the 
inserted disk is valid. If the disk is not valid, your application can use the Disk Initializa- 
tion Manager to present the user with the standard interface for initializing the disk. 

To use this chapter, you should already be familiar with the Event Manager, which sends 
your application a disk-inserted event whenever a disk is inserted (unless you have 
masked out such events). You need to examine the message field of that event to 
determine whether the inserted disk is already initialized. You also need to be familiar 
with the File Manager if your application changes the default volume characteristics of 
newly irutialized volumes. 

This chapter begins by describing the operation of the Disk Irutialization Manager, 
including 

■ formatting, verifying, and zeroing a disk 

■ the standard user interface for initializing and naming a disk 

■ bad block sparing 

Then this chapter shows how you can 

■ determine whether an inserted disk is valid 

■ present the standard user interface to initialize and name an invalid disk 

■ present the standard user interface to erase a disk 

■ initialize or erase a disk without using the standard user interface 

■ change the default volume characteristics of newly initialized volumes 



About the Disk Initialization Manager 



The Disk Initialization Manager is the part of the Macintosh Operating System that 
manages the process of initializing disks. This package accepts requests to initialize a 
disk and translates them into control calls for the corresponding disk driver. The Disk 
Irutialization Manager itself does not perform the low-level formatting or verification of 
the disk; instead, it simply manages the communication between the software requesting 
that a particular disk be iiutialized and the appropriate disk driver. 
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In theory, you can use the Disk Initialization Manager to initialize any 
writable disk drive. In practice, however, most SCSI disk drivers ignore 
formatting control calls. Instead, low-level disk operations such as 
formatting and verification are usually performed by a utility program 
supplied with the disk. As a result, this chapter assumes that the disk to 
be initialized is a 3.5-inch floppy disk or an Apple Hard Disk 20SC, all of 
which are accessed through the Disk Driver. ♦ 

Usually, the Finder or the Standard File Package calls the Disk Initialization Manager 
when the user ir^serts an uninitialized disk. Occasionally the user will insert a disk when 
your application is frontmost. At that time, the Operating System generates a 
disk-inserted event. If your application has not masked out such events, it receives an 
event record for that event when it makes an event call and no events with higher 
priority are pending. You then need to determine whether the inserted disk is valid (as 
indicated by a value in the event record). If the disk is not valid, you should call the Disk 
Initialization Manager to allow the user to initialize the disk or, if desired, eject it. 

If your application masks out disk-inserted events, the event stays in the event queue 
until your application calls the Standard File Package (which automatically processes 
disk-inserted events) or until the current application can handle disk-inserted events. In 
general, it's best not to mask out disk-inserted events and to handle them as described 
later in this chapter; otherwise, the user is likely to become confused when, after 
inserting an uninitialized or damaged disk, no disk icon appears on the desktop and ho 
standard disk initialization dialog box appears. (Icons of initialized and tmdamaged 
disks always appear on the desktop, even if the current application ignores disk-inserted 
events.) 

Disk Initialization 

Disk initialization is the process of making a disk usable by the Macintosh Operatiung 
System. When shipped, most floppy disks are uninitialized because different operating 
systems have different initialization requirements. On Macintosh computers, disk 
initialization consists of three independent steps: 

■ disk formatting 

■ disk verification 

■ disk zeroing 

All three steps must be performed successfully before the disk is considered initialized 
(or valid). You can use a single Disk Initialization Manager function, DIBadMount, 
to perform all three operations in sequence, or you can perform any one of them by 
calling a corresponding low-level function (either DiFormat, DIVerify, or DIZero). 
In general, your application should use the standard user interface described in the 
following section to initialize a disk. 

The first step in the initialization process is disk formatting. Formatting a disk consists 
of writing special information onto a disk so that the disk driyer can read from and write 
to the disk. This involves dividing the total usable space into sectors and tracks. See the 
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chapter "Disk Driver" in Inside Macintoshf Devices for a description of how a disk is 
divided into tracks and sectors. 

the second step in the disk-initialization process is disk.verificalion. Verifying a disk 
consists of reading every bit on the disk to ensure that the disk has been formatted 
correctly and contains no bad blocks. If in error occurs during the reading of any single 
bit, the verification is considered vinsuccessful. 

The third and final step in the disk-iiutialization process is disk zeroing, Zeroing a disk 
consists of creating on the disk the data structures and files necessary for the disk to be 
recognized as a hierarchical file system (HiFS) volume. In particular, zeroing a disk places 
a master directory block (MDB), a volume bitmap, and a catalog ffle in appropriate 
locations on the disk. (For information on the locations and sizes of these items, see the 
description of the organization of data in a volume in the chapter "File Manager" in 
this book.) The volume bitmap and catalog file are set up to represent a volume contain- 
ing no xiser files. As a result, zeroing a disk makes any files previously located on the 
disk iriaccessible. 

Beginning in system software version 7.0, zeroing a disk also causes the Disk 
Initializatibn Manager to attempt to remove any bad blocks (as identified during the 
disk-verification process) from the pool of available blocks on the disk. See "Bad Block 
Sparing" on page 5-7 for a description of this capability. 

The Disk Initialization User Interface 

The Finder and the Standard File Package both handle disk-inserted events for 
uninitialized disks by presenting a disk initialization dialog box asking the user 
whether the disk should be ejected or initialized. Your application too can easily call a 
Disk Initialization Manager routine that generates such a dialog box when the user 
inserts an invalid disk. Figure 5-1 illustrates one configuration of ti^e dialog box. 



Figure 5-1 The disk initialization dialog box 



JL^ This disk is unreadable: 

Do you uiant to initialize it? 



Eject I (one-Sided) (Two-Slded] 



The appearance of the disk irutialization dialog box changes to rieflect changing 
conditioiis. For example, the icon changes to show which drive contains the disk. Also, 
the text of the dialog box changes according to what is wrong with the disk. The text 
might read "This is not a Macintosh disk" if the Disk Initialization Manager detects that 
the disk has been formatted for use on another operating system. Or, it might notify tiie 
liser that a high-density disk can be used only on an Apple SuperDrive. Finally, if a user 
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inserts a single-sided disk into any disk drive, or a high-density disk into a high-density 
disk drive, then the EHsk Initialization Manager changes the buttons in the dialog box, as 
illustrated in Figure 5-2, because such disks can be formatted in only one way. 



Figure 5-2 Alternate buttons for the disk initialization dialog box 



-i^ This disk is unreadable: 

Do you want to initialize it? 



[ Initialize^ 



Regardless of the initial appearance of the disk initialization dialog box, it disappears if 
the user clicks Eject or Cancel. If, however, the user decides to initialize the disk, the text 
in the dialog box changes to warn the user that initialization erases any previous data on 
the disk, as illustrated in Figure 5-3. 



Figure 5-3 The disk initialization warning 



This process will erase all 
information on this disk. 



[ Cancel"^ 



Erase 



Finally, if the user decides to initialize the disk, the contents of the dialog box change so 
that the user can name the new disk, as illustrated in Figvire 5-4. 



Figure 5-4 The disk naming dialog box 




After the user names the disk, the Disk Initialization Manager attempts to initialize it. 
If an error occurs and the initialization fails, an alert box notifies the user, and the disk 
is ejected. 
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The Disk hutialization Manager also provides a mechanism for using the standard 
interface to reinitialize disks that are already formatted. (This mechanism is useful, for 
example, when the user wants to reinitialize single-sided disks as double-sided disks.) 
The Finder takes advantage of this mechanism with its Erase Disk command, iUustrated 
in Figure 5-5. After the user selects the erase operation from this dialog box, the reinitial- 
ization begins immediately, without hirther warnings. If desired, your appHcation can 
use this same standard interface to allow users to reinitiaUze mounted disks (other than 
the startup volume). Your application can customize the text to be displayed in such a 
dialog box. Note that only a few utility applications achially need to provide users with 
this capability. 

Figure 5-5 The Rnder*s disk erasing dialog box 



Completely erase disk named 
^ "Balsa's Games" (internal driue)? 



I Cancel || (one-Sided) fTufo-Sided) 



If you are writing a utihty program such as a disk-copying application, you might wish 
to initialize new disks or reinitialize valid disks without displaying the standard disk 
initialization dialog box. For example, your application might allow users to initialize 
multiple disks without having to respond to the standard dialog box each time. The Disk 
Initialization Manager provides low-level routines that allow you to do so. Unless you 
are writing a utility program of this type, you don't need to use these routines. 

Bad Block Sparing 



Beginning with system software version 7.0, the Disk InitiaHzation Manager tries to 
initiaUze a disk even if it contains some bad blocks; this feature is caUed bad block 
sparing. Without bad block sparing, the Disk Initialization Manager considers a disk 
unusable even if just one block is bad. With bad block sparing, however, the Disk 
Initialization Manager attempts to work around the bad block by removing it from the 
pool of available free blocks. This prevents the File Manager from allocating the block 
to a file. Except in cases (described later) involving critical blocks on a disk, the Disk 
Initialization Manager can usually initialize a disk that would previously have been 
rejected as invalid. This section describes the operation of bad block sparing. 

WARNING 

AppUcations that manipulate disks using File Manager routines are 
imaffected by bad block sparing. Software that accesses blocks directly 
from the disk or that makes assumptions about the physical blocks on a 
disk (such as a disk scavenger, recovery, or backup utility) is likely to fail 
or cause a loss of data on disks containing spared blocks. A 
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The bad block sparing occurs during the disk-zeroing phase of disk initialization. As a 
result, sparing occurs only when you call DIZero or DIBadMount (which internally 
calls DIZero), never when you call DIPormat .or DIVeri f y. The only visible sign 
of the sparing process is an additional dialog box that contains the message 
"Re-Verifying Disk/' 

Disks without bad blocks are irutialized exactly as in previous versions of system soft- 
ware. The sparing algorithm is invoked only if the disk verification fails during a call to 
the DIBadMount function or if the DIZero function encounters bad blocks during its 
zeroing. The sparing algorithm proceeds by making a second pass over the disk, writing 
and then reading back a test pattern. This testing is done a single track at a time. If any 
retries or errors occur during this test, all the sectors in the track are deemed bad. 

If more than 25 percent of the disk is found to contain bad blocks, if the 1/ O errors 
appear to be due to hardware failure rather than media failure, or if certain critical 
sectors (described later) are bad, then the initialization fails just as it would have without 
the bad block sparing. Otherwise, the HFS volume structure is written to the disk. After 
the volume structure has been written, the Disk Irutialization Manager performs several 
further operations during bad block sparing. 

1. It sets the appropriate bits in the volume bitmap to indicate that thie bad blocks are 
allocated to a file. 

2. It creates file extent descriptors for the bad blocks and inserts them into the volume 
extents B*-tree so that the free-space scavenging that occurs at voliune mount time (or 
that is done by disk utilities such as Disk First Aid) does not reintroduce the bad 
blocks into the volume bitmap. A special file ID (5) is used for these extents. 

3. It sets bit 9 in the drAtrb field of the master directory block to indicate that bad 
blocks in the disk have been spared. 

4. On 800K floppy disks only, it reduces the number of allocation blocks on the disk 
by 1 (from 1594 to 1593), to prevent previous versions of the Finder from doing 
disk-to-disk copies physically (that is, sector by sector). This copying operation 
would fail during an attempt to copy the bad blocks. The Finder does physical 
copies as an optimization only on disks Containing exactly 1594 allocation blocks. 

The critical sectors (those that must be good even on a spared disk) include the boot 
blocks, the master directory block and the spare master directory block, the volvime 
bitmap, and the initial extents for the catalog and extents B*-tree files of the volume. 

Notice that the bad block sparing algorithin does not create any new entries in the 
volvime's catalog file. In other words, steps 1 and 2 of the algorithm trick the File 
Manager into thinking that the bad blocks have been allocated to some file, although no 
file is actually created to contain those blocks. For this reason, directory emmierations 
and file-by-file copies can proceed as they would have without bad block sparing. (If a 
file were created for the bad blocks, that file would need a parent directory; in that case, 
reading the catalog file to determine how many files that directory contains would 
produce erroneous results.) 
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Note 

The bad block sparing capability described in this section applies 
only during disk initiaUzation. The Operating System cannot 
correct problems that occur after a disk has been initialized 
(except by reinitializing the disk). ♦ 



Using the Disk Initialization Manager 



The Disk Initialization Manager provides standard interfaces that allow your application 

■ to respond to the user's insertion of an unformatted or damaged disk by presenting 
the standard disk initialization dialog box 

■ to reinitiahze vaUd disks, preserving their names but deshroying their contents 
You can override these standard interfaces by calling low-level Disk Initialization 
Manager routines, and you can also override the default volume characteristics that the 
Disk Initialization Manager gives to hierarchical volumes. 

Responding to Disk-Inserted Events ^ 

When the user inserts a disk, the Operating System attempts to mount the volume on the 
disk by calling the File Manager function PBMountVol. If the volume is successfuUy 
mounted, an icon representing the disk appears on the desktop. TTie Operating System 
then generates a disk-inserted event. If the user is interacting with a standard file dialog 
box, the Standard File Package intercepts the disk-inserted event and handles it. 
Otherwise, the event is left in the event queue for your application to rehdeve. 
Your application must either mask out disk-inserted events or process them by checking 
to see whether the inserted disk is invalid. If you mask out such events, then each 
disk-inserted event needlessly occupies a position in the event queue until the user 
brings an application that can handle such events to the foreground or until your | 
application invokes the Standard File Package. Also, displaying the disk mihahzataon ^ 
dialog box long after the disk has been inserted is Ukely to confuse the user. However, | 
you might wish to mask out disk-inserted events when you create modal dialog boxes m n 
which you process events with WaitNextEvent rather than ModalDialog. That way, g 
your appUcation can process disk-inserted events as soon as the modal dialog box closes. 2 



Note 

By default, the Dialog Manager's ModalDialog procedure 
automatically masks out disk-inserted events so tiiat your appUcation 
can handle them when dialog boxes dose. If you wish to accept 
disk-inserted events in a modal dialog box in which you call 
ModalDialog, you must supply a filter procedure for the dialog box. 
See the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox 
Essentials for information on how to write a filter procedure. ♦ 
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Because handling disk-inserted events is easy, there is no good reason for your 
application to mask out the events in its main event loop. Listing 5-1 defines a 
procedure that your application can call when it receives a disk-inserted event. 



Listing 5-1 Responding to disk-inserted events 



PROCEDURE DoDiskEvent (myEvent: EventRecord) ; 
VAR 

my.Point: Point; 
my Err: OSErr; 
BEGIN 

IF HiWord (myEvent .message) <> noErr THEN 

(attempt to mount was unsuccessful} 
DILoad; (load Disk Initialization Manager} 

SetPt (myPoint, 120, 120); (set top left of dialog box} 

myErr : = DIBadMount (myPoint , myEvent .message) ; 

■{notify the user) 
DIUnload; {unload Disk Initialization Manager} 

END 

(attempt to mount was successful} 
(do other processing} 



END; 



The DoDiskEvent procedure in Listing 5-1 checks the high word of the event message 
to see if the disk is mounted properly If it has not been mounted, DoDiskEvent calls 
the Disk Initialization Manager's DIBadMount function, which displays the disk 
initialization dialog box. Before doing so, DoDiskEvent calls DILoad to ensure that the 
Disk Initialization Manager and its dialog box are loaded into memory. If you did not 
caU DILoad and the user started up with a floppy system startup disk, the Operating 
System might require that the user reinsert the system disk and might then attempt to 
initialize that disk. In Listing 5-1, if the user did start up with a floppy system startup 
disk on a single floppy-drive system, the DILoad procedure requests that the user insert 
the system disk so that it can read the necessary resources, and then it ejects that disk so 
that the user can again put the disk to be initialized into the drive. After calling 
DIBadMount to handle the uninitialized disk, DoDiskEvent calls DIUnload to release 
the resources DILoad read into memory. 

Beginning with system software version 7.0, the first parameter to DIBadMount is 
ignored, and the disk initialization dialog box is automatically centered on the screen. 
The procedure in Listing 5-1 ignores the result code rehimed by DIBadMount because 
ordinarily it does not concern your application. If an error does occur during initializa- 
tion, DIBadMount informs the user and ejects the disk. 
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Erasing Initialized Disks 

You can use the standard interface provided by the DIBadMount function to reinitialize 
disks that are already initialized correctly. Doing so permanently erases their contents, 
but does not change their names. 

To reinitialize a disk, caU DIBadMount with the high word of the event message equal to 
the result code noErr. The DIBadMount function presents the standard interface to 
initialize the disk in the drive whose number is specified by the low word of the event 
message. However, because the Disk liutialization Manager carmot know why your 
application wishes to reinitialize a disk, it cannot provide the initial text for the disk 
initialization dialog box. Therefore, your application must use the Dialog Manager's 
ParamText procedure to create a customized message, as illustrated in Listing 5-2. 

If you need to reinitialize a valid disk but do not have access to the event message from 
when the disk was formatted, you can artificially create an event message by setting the 
event message to an integer representing the drive niunber, as follows: 

my Event .message := driveNum; 

Doing so sets each of the high-order bits of the artificial event message to 0, which is 
desired because the constant noErr is equal to 0. 

Listing 5-2 defines a procedure for displaying a disk iiutialization dialog box that allows 
the user to reirutialize the disk in the drive specified by driveNum. The disk initializa- 
tion dialog box displays the text specified in the myStr ing parameter. The procedure in 
Listing 5-2 in turn calls a procedure named DoError. You must define DoError to 
process the result code if the initialization did not successfully complete. The disk initial- 
ization dialog box does alert the user if the operation is not successfully completed, and 
the disk is ejected. However, your application might need to know that a formerly 
mounted disk is no longer mounted because reiiutialization failed. 



Listing 5-2 Reinitializing a valid disk 

PROCEDURE DoEraseDisk (driveNum: Integer; myString: Str255) ; 
VAR 

inyPoint : Point ; 

itiyErr: Integer; {result code) 

BEGIN 

DILoad; {load Disk Initialization Manager} 

ParamText (nr/String, " , ' ' , * ' ) ; (set dialog text} 
SetPt (in/Point , 120, 120); {set top left of dialog box} 

myErr := DIBadMount (my Point , driveNum); 

{allow user to confirm erase} 

IF myErr <> noErr THEN 

DoError (myErr) ; {respond to error, if necessary} 

DIUnload; {unload Disk Initialization Manager} 

END; 
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Overriding the Standard Initialization Interface 

The disk initialization dialog box provides an easy-to-use, standard interface for 
irutializing and reinitializing disks. However, if you wish, you can use three low-level 
Disk liutialization Manager functions that accomplish the three stages of disk 
initialization without presenting any user interface. The three functioris are DI Format, 
DIVeri f y, and DIZero. The DIFormat function attempts to format the disk, the 
DiVerify ftmctioh verifies whether the format was successful, and the DIZero 
fimction updates the newly initialized volume's characteristics and attempts to spare 
any bad blocks on the disk. 

Listing 5-3 shows how to reinitialize a disk without using the standard interface, llie 
low-level functions work orJy if the disk is not already mounted in the disk drive. 
Therefore, Listing 5-3 uses high-level File Mariiager calls to unmount the volume and to 
remember the volume's name, so that it can be restored later. Because you are no longer 
using the standard interface, you must define the DoError procedure so that you can 
alert the user about an error. 



Listing 5-3 Reinitializing a validly formatted disk without using the standard interface 



{result code} 
{name of volume} 
{to unmount volume} 
{for GetVInfo call) 

{load Disk Init . Manager} 



PROCEDURE DoEraseDisk (driveNum: Integer); 
VAR 

myErr: OSErr; 
volName: Str255; 
oldVRefNum: Integer; 
oldFreeBy tes : Longint ; 
BEGIN 

DILoad; 

myErr := GetVInfo (driveNum, ivolName, oldVRefNum, oldFreeBytes) ; 

{remember name of volume} 

IF myErr = noErr THEN 

myErr := UnmountVol ( ©volName , oldVRefNum); 

{unmount the disk} 

IF myErr = noErr THEN 

myErr := DIFormat (driveNum) ; 
IF myErr = noErr THEN 

myErr := DiVerify (driveNum) ; 
IF myErr = noErr THEN 

myErr := DIZero (driveNum, volName) ; 
IF myErr <> noErr THEN 

DoError (myErr ) ; 
DIUnload; 
END; 



{format the disk} 

{verify format } 

{update volume information} 

{respond to error} 
{unload Disk Init. Manager} 
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If you wish, you can also respond to a user's insertion of an uninitialized or damaged 
disk by simply formatting the disk without using the standard interface. Listing 5-4 
defines a procedure for this purpose. Listing 5-4 differs from Listing 5-3 only in that it 
does not begin by unmoimting the volume (because the File Manager does not movint 
urunitialized or damaged disks). 



Listing 5-4 Initializing an uninitialized disk without using the standard interface 



PROCEDURE DoInitDisk (driveNum: Integer; volName: Str255) ; 
VAR 

myErr : OSErr ; 

BEGIN 

DILoad ; 

myErr DIFormat (driveNuin) ; 
IF myErr = noErr THEN 

myErr := DIVerify (driveNum) ; 
IF myErr = noErr THEN 

myErr := DI Zero (driveNum, volName) ; 
IF myErr <> noErr THEN 

DoError (myErr) ; 
DIUnload; 
END; 



{result code} 

{load Disk Init . Manager} 
{format the disk} 

{verify format} 

{update volume information} 

{respond to error} 
{unload Disk Init. Manager} 



Ch anging Default Volume Characteristics 

The Disk Initialization Manager must set certain volume characteristics v/hen it creates 
an HFS directory on a volume. Default values for these characteristics are stored in an 
HFS defaults record in ROM. If you wish, you can override those defauh values by 
placing a pointer to an HFS defaults record in the low-memory global variable 
FmtDe faults. The Disk Initialization Manager uses the record stored in ROM 
whenever this low-memory global variable contains NIL. 

IMPORTANT 

Most applications do not need to alter the default voliune characteristics. 
This technique is useful primarily for applications, such as backup 
utilities, that intelligently adjust the allocation block size and climip 
size to maximize the amount of data written to a backup volume. A 
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The HFSDef aults data structure defines the HFS defaults record. 



TYPE HFSDefaults 
RECORD 

sigWord: 

abSize : 

clpSize : 

nxFreeFN: 

btClpSize: 

rsrvl : 

rsrv2 : 

rsrv3 : 
END; 



PACKED ARRAY [0..1] OF Byte; 
Long In t ; 
Longlnt ; 
Longint ; 
Longlnt ; 
Integer; 
Integer; 
Integer; 



{signature word} 

{allocation block size in bytes} 

{clump size in bytes} 

{next free file number} 

{B*-tree clump size in bytes} 

{reserved} 

{reserved} 

{reserved} 



Field descriptions 

sigWord 



abSize 



The signature word to be used for newly iiutialized volumes. By 
default, this field is set to ' BD ' (hexadecimal $4244). You must set 
this field to ' BD ' for the volume to be recogruzed as an HFS 
volume. 

The number of bytes in each allocation block on newly initiaHzed 
volumes. If you set this field to 0, the number of bytes in each 
allocation block is computed according to the following formula: 

abSize = (1 + (blocks in volume/64K)) * 512 bytes 
By default, this field is set to 0. 

The number of bytes to be used for the clump on newly initialized 
volumes. By default, this field is set to 4*abSize. 
The next free file number on newly initialized volimies. By default, 
this field is set to 16. 

The number of bytes to be used for the B*-tree clump on newly 
irutialized volumes. If you set this field to 0, the nuinber of bytes to 
be used for the B*-tree dump is computed according to the 
following formula: 

btClpSize = ((blocks in volume) /128) * 512 bytes 

By default, this field is set to 0. 
Reserved. Set to 0. 
Reserved. Set to 0. 
Reserved. Set to 0. 

The code in Listing 5-5 fills in an HFSDefaults record, stores it in the system heap (so 
that the record remains in memory after the application terminates), and makes the 
low-memory global variable FmtDef aults a pointer to that record. Note that changing 
the default volume characteristics does not affect volimies that you have already 
initialized, but only voliunes to be initialized. 



clpSize. 

nxFreeFN 

btClpSize 



rsrvl 
rsrv2 
rsrv3 
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Listing 5-5 Changing default volume characteristics 



PROCEDURE ChangeHFSDefaults; 
CONST 

FmtDefaults = $039E; {address of low-memory global} 

TYPE 

HFSDefaultsPtr = "HFSDef aults ; {pointer to override record) 

HFSDefaultsAdd = "HFSDefaultsPtr; {address of above pointer] 

VAR 

myDefaults: HFSDefaultsPtr; 
BEGIN {allocate record in system heap) 

myDefaults := HFSDefaultsPtr (NewPtrSysClear (SizeOf (HFSDefaults) ) ) ; 
WITH myDefaults^ DO 
BEGIN 

{set fields of record) 

END; 

HFSDefaultsAdd (FmtDefaults) := myDefaults; 

{change value of global) 

END; 

If you later want to restore the default settings, you can reset the low-memory global 
variable FmtDefaults to NIL. Remember to delete any memory you have allocated. 
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This section describes the routines that are specific to the Disk Initialization Manager. See 
"Changing Default Volume Characteristics" on page 5-13 for a description of the Pascal 
data structure for the HPS defaults record . 



Routines 

The Disk Initialization Manager provides two routines (DILoad and DlUnl oad) that 
allow you to load and imload the package. The DIBadMount routine has two uses: to 
format uninitialized disks that the user inserts and to reirutialize volumes by erasing 
their data without changing their names. Last, three low-level routines (DlFormat, 
DiVer i f y, and DiZero) allow you to perform the steps of formatting, verifying, and 
zeroing the disk separately. 

Loading and Unloading the Disk I nitialization Manager 

Even a user with a hard disk drive might occasionally use a floppy disk to start up the 
computer. When you call the Disk Irutialization Manager to initialize a disk, it might 
need to read a resource from the System resource file. If the disk containing the System 
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resource file is not already mounted, the user might need to switch disks, and system 
software might accidentally try to reinitiaUze the startup volume. The DILoad procedure 
aUows you to avoid this problem by ensuring that the resources the Disk h^idalization 
Manager needs are preloaded into memory. The DIUnload procedure reverses the 
effects of DILoad. 



You can use the DILoad procedure to ensure that the Disk Initialization Manager and its 
associated dialog box and dialog items are in memory. 

PROCEDURE DILoad; 



DESCRIPTION 



The DILoad procedure reads the Disk InitiaUzation Manager and its associated dialog 
box and dialog items into memory and makes them unpurgeable. Depending on which 
Macintosh model the user is using, the Disk Initialization Manager and the dialog box 
and dialog items are either in ROM or in the System file. 

Ordinarily, you call the DILoad procedure when you anticipate that the user will need to 
format a disk. The Standard File Package automatically calls DILoad when you call 
StandardGetFile or StandardPutFile. If you are writing a utility program that 
frequently needs to iiutialize disks, such as a disk-copying program, you might call 
DILoad at the beginning of your application. 

When you use the low-level disk-initialization routines DIFonnat, DIVerify, and 
DIZero, the Disk Initialization Manager does not need to load a dialog box. Therefore, 
if you use only these routines, you can (if you wish) call the Resource Manager to read 
just the package resource into memory and the Memory Manager procedure to make 
it unpurgeable. To read just the package resource into memory, you can call the 
GetResource function with a resource ID of 2 and a resource type of ' PACK * . Then, 
you need to use the HNoPurge procedure to make the package resource unpurgeable. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for DILoad are 
Trap macro Selector 

Pack2 $0002 



SPECIAL CONSIDERATIONS 



DERATIONS 

Because the DILoad procedure aUocates memory, you should not call it at interrupt time. 
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DIUnload 



To free the memory space occupied by the Disk Initialization Manager, you can call the 
DIUnload procedure. 

PROCEDURE DIUnload; 

DESCRIPTION 

The DIUnload procedure makes the Disk Initialization Manager and its associated 
dialog box and dialog items purgeable. They remain in memory until the Memory 
Manager purges the heap zone. 

If you are using the low-level disk initialization routines and read just the package 
resource into memory, you can free the memory the package occupies by calling the 
ReleaseResource procedure. 

To force the Memory Manager to purge the heap zone so that it really frees the memory 
occupied by the Disk Initialization Manager and its dialog box and dialog items, you 
can call one of the Memory Manager routines PurgeMem and MaxMem. For more 
information, see the chapter "Memory Manager" in Inside Macintosh: Memory. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for DIUnload are 

Trap macro Selector 

_Pack2 $0004 

SPEQ AL CONSIDERATIONS 

Because DIUnload might affect memory, you should not call it at interrupt time. 

Initializmg a Disk 

You can use the Disk Initialization Manager to initialize uninitialized disks and to 
reinitialize previously initialized disks. The DIBadMount function accomplishes 
both tasks. 
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To respond to the user's insertion of an uninitialized or damaged disk, you can call the 
DIBadMount function. , 

FUNCTION DIBadMount (where: Point; evtMessage: Longint) : Integer; 

where The desired location, in global coordinates of the "PP^'-'^J^^^^j; J^^*^ 

disk initialization dialog box. In system software versions 7 0 and later, 
this parameter is ignored, and the dialog box is automaticaUy centered on 

the screen. 

evtMessage The event message received when the disk is i^erte^ Tlie high word of 
this message contains the result code associated with *e disk msertion. 

The low word of this message indicates the number of the drive into 
which the user inserted the disk. 



n.e DIBadMount function evaluates the result code in the high word of the evtMessage 
parameter and responds appropriately. If the result code is noEr r, the funcbon allows 
fte user to erase the contents of the disk. If the result code is ioErr, badMDBErr, or 
noMacDskErr, initializing the disk might correct the problem, and so ^^.^.^f 
displays a dialog box that explains the problem and allows the user to miha^^e the disk. 
If the result code is extFSErr, memFullErr, nsDrvErr, paramErr, or volOnLinErr 
then initializing the disk would not correct the problem. In this case, DIBadMount ejects 
the disk from the drive and returns the result code. 

Before presenting the disk initialization dialog box, DIBadMount checks whether the 
drive contains an already mounted volume. If so, it ejects the disk and refems 2 as its 
result, -nus happens rarely and could reflect an error in your applicabon (for example, 
you forgot to call DILoad, and the user had to switch to the disk contaimng the System 
resource file). 

The DIBadMount function uses just one disk initialization dialog box to cover all disk 
initialization situations. The dialog box contains many dialog items, which are hidden 
and shown as appropriate. The dialog box always contains an icon mdicating the drive 
containing the disk to be initialized. 

The initial text of the disk initialization dialog box depends on the result code received. 
For example, if you pass noMacDskErr to DIBadMount in the evtMessage parameter, 
the dialog box displays the text "This is not a Macintosh disk." If you pass the result 
code noErr, you can customize the message by using the Dialog Manager s ParamText 
procedure. 

The disk initiaUzation dialog box contains a button allowing the user to cancel the 
iiulialization and one or two buttons allowing the user to request inibalizahonof 
the disk. Usually, the cancel button is labeled Eject, but if the result code pa^ed to 
DIBadMount within the evtMessage parameter is noErr, then the cancel button is 
labeled Cancel. If the user responds to the disk initialization dialog box by dickmg 
the Eject button, DIBadMount ejects the disk and rehims 1 as its result If ttie user 
clicks the Cancel button, DIBadMount returns 1 but does not eject the disk. 
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m most cases, the Initialize button is the only alternative to the Eject or Cancel button. 
However, if the user inserts a double-sided (but not high-density) disk into a 
double-sided or high-density disk drive,DIBadMountpr^entsbuttons^^^^^^^^^^ 

Onesided and Two-Sided. The user can then decide whether to make the disk 
sinele-sided or double-sided. If the user clicks the Inibalize button, the One-S.ded 
button or the Two-Sided button, DIBadMount warns the user that the mitialization 

erases any existing data on the disks.lf the user proceeds, ni^^^^^^^^ 
L user to name the disk if it is not already named and then updates the text ofthe 

dialogbox to inform the user of the progress of the operation. If the op^ation fa^s 

DIBadMount alerts the user and ejects the disk, returning an appropriate result code. 

You can use DIBadMount to format hard disks as well as floppy disks. However, you 

should not attempt to format the startup volume. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for DIBadMount are 

Trap macro Selector 

Pack2 $0000 



SPECIAL CONSIDERATIONS . ,-,11 ;f at 

Because the DIBadMount function might allocate memory, you should not call it at 

interrupt time. 



RESULT CODES 



[no name] 2 Disk in specified drive is already mounted 

[no name] 1 User canceled initializing 

noErr 0 No error 

paramErr -50 Drive number specified is bad 

volOnLinErr -55 Volume is ^ready onlme 

nsDrvErr -56 Nosuchdnve 

o„^Fc;Prr -58 Disk has external file systcm 

CstDskErr -64. Last of the range of low-level disk errors 

firstDskErr -84 First of the range of low-level disk errors 

memFullErr -108 Not enough memory 



Low-Level Disk Initialization Routines 



If you do not want to use the standard interface for initializing uninitiahzed volumes, 
you can use the Disk Initialization Manager's low-level routines. For example, if you are 
writing a disk-copying application, initializing a disk might be only part of the copymg 
pr^lln this caTyouLghtwish to create your o^ 

about the repercussions of initializing a disk and giving information on tiie progress of 
the initialization. 
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The three low-level disk-initialization routines are DlFormat, DIVerify, and DIZero. 
Ordinarily, you call them ir> that order to format an ururutialized disk, to verify the 
format, and to set the volume's volume iivformation block and catalog. 



DlFormat 



To format a disk, you can xise the DlFormat function. 

FUNCTION DIForinat (drvNum: Integer) : OSErr; 

drvNum The nim\ber of the drive containing the disk to be formatted. 



DESCRIPTION 



The DIFermat function attempts to format the disk in the drive specified by the drvNum 
parameter and returns a result code indicating whether it completed \he formatting 
successfully or failed. Formatting a disk consists of writing special ii\formation onto it 
so that the disk driver can read from and write to the disk. 

You can use DlFormat to format any unlocked disk, including sirigle-sided disks, 
double-sided disks, high-density disks, and hard disk drives. It fonnats both sides 
of a double-sided disk. 

You have to unmount a disk before calling the DlFormat function. 



ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for DlFormat are 
Trap macro Selector 

Pack2 $0006 



SPECIAL CONSIDERATIONS 

You should not call DlFormat at interrupt time. 



RESULT CODES 

noErr 0 No error 

volOnLinErr -55 Volxmie is online 

lastDskErr ; -64 Last of the range of low-level disk errors 

f ir s t DskEr r -84 First of the range of low-level disk errors 



5-20 



Disk Initialization Manager Reference 



TIVO-408871 



CHAPTER 5 

Disk Initialization Manager 



DIVerify ' • 

• To verify a disk you have formatted, you can use the DIVer i f y function. 
FUNCTION DIVerify (drvNum: Integer) : OSErr; 
drvNum The number of the drive containing the disk to be verified. 

DESCRimON 

The Diver i fy function verifies the format of the disk in the drive specified by the 
drvNum parameter. It reads each bit from the disk and returns a result code indicating 
whether all bits were read successfully or not. The DIVer i f y function does not affect 
the contents of the disk itself. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for DIVer i fy are 

Trap macro Selector 

Pack2 $0008 



SPECIAL CONSIDERATIONS 

You should not call DIVer i f y at interrupt time. 



RESULT CODES 

noErr 0 No error 

las tDskErr -64 Last of the range of low-level disk errors 

f ir St DskErr -84 First of the range of low-level disk errors 



DIZero 



g 



To complete the disk-initialization process, you can use the DIZero function. | 
FUNCTION DIZero (drvNum: Integer; volName: Str255) : OSErr; ^ 



CD 



drvNum The number of the drive containing the disk to be zeroed. 
volName The name of the volume (to be included in the volume information). 



DESCRimON 



On the unmounted volume in the drive specified by the given drive number, the DIZero 
function sets the volume information, the volume bitmap, a fUe directory, and the 
desktop database (or desktop file) to the settings corresponding to a volume with no 
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files. This function completes the process of making any files previously on the volume 
permanently inaccessible. If the operation faUs, DIZero returns a result code indicating 
that a low-level disk error occurred. Otherwise, it mounts the volume by calling the File 
Manager function PBMountVol and retunis that function's result code. 

ASSEMBLY-LANGUAGE INFORMATION 

The trap macro and routine selector for DI Zero are 
Trap macro Selector 

_Pack2 $000A 

SPECIAL CONSIDERATIONS 

You should riot call DIZero at interrupt time. In system software version 7.0 and later, 
DIZero automatically performs bad block sparing, as described in "Bad Block Sparing/' 
beginning on page 5-7. 



RESULT CODES 



noErr 


0 


No error 


ioErr 


-36 


I/O error 


paramErr 


-50 


Drive number specified is bad 


volOnLinErr 


-55 


Volume is already oiUine 


nsDrvErr 


-56 


No such drive 


noMacDskErr 


-57 


Disk is not a Macintosh disk 


extFSErr 


-58 


Disk has external file system 


badMDBErr 


-60 


Master directory block is bad 


lastDskErr 


-64 


Last of the range of low-level disk errors 


f irstDskErr 


-84 


First of the range of low-level disk errors 


memFullErr 


-108 


Not enough memory 
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Summary of the Disk Initialization Manager 



Pascal Summary 



Data Types 



HFS Defaults Record 



TYPE HFSDefaults = 
RECORD 

sigWord: 
abSize: 
"clpSize: 
. rixFreeFN : 
btClpSize 
rsrvl : 
rsrv2 : 
rsrv3 : 
END; 

Routines 



PACKED ARRAY [0..1] OF Byte; 
Longint ; 
Longint ; 
Longint ; 
Longint ; 
Integer; 
Integer; 
Integer; 



{signature word} 

{allocation block size in bytes} 

(clump size in bytes} - 

{next free file number} 

{B*-tree clump size in bytes} 

{reserved} 

{reserved} 

{reserved} 



Loading and Unloading the Disk Initialization Manager 

PROCEDURE DILoaO; 
PROCEDURE DIUnload; 

Initializing a Disk 

FUNCTION DIBadMount 



I 



(where: Point; evtMessage: Longint): Integer; 



g 



o 

3 



to 

CD 



Low-Level Disk-Initialization Routines 

FUNCTION DIFormat (drvNum: Integer): OSErr; 

FUNCTION DIVerify (drvNum: Integer): OSErr; 

FUNCTION DIZero (drvNum: Integer; volName: Str255) : OSErr; 



Summary of the Disk Initialization Manager 
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C Summary 



Data Types 



HFS Defaults Record 

struct HFSDefaults { 



char 


sigWord[2] ; 


/*signature word*/ 


long 


abSize; 


/♦allocation block size in bytes*/ 


long 


clpSize; 


/*clump siize in bytes*/ 


long 


nxFreeFN; 


/*next free file number*/ 


long 


btClpSize; 


/*B-Tree clump size in bytes*/ 


short . 


rsrvl; 


/♦reserved*/ 


short 


rsrv2 ; 


/♦reserved*/ 


short 


rsrv3 ; 


/♦reserved"^/ 



}; 

typedef struct HFSDefaults HFSDefaults; 
Routines 

Loading and Unloading the Disk Initialization Package 

pascal void DILoad (void) ; 

pascal void DIUnload (void) ; 

Initializing a Disk 

pascal short DIBadMount (Point where, long evtMessage) ; 

Low-Level Disk-Initialization Routines 

pascal OSErr DIFormat (short drvNum) ; 

pascal OSErr DIVerify (short drvNum) ; 

pascal OSErr DIZero (short drvNum, const Str255 volName) ; 
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Assembly-Language Summary 



Data Structures 



HFSDef aults Data Structure 



0 


sigWord 


word 


signature word 


2 


abSize 


long 


allocation block size in bytes 


6 


clpSize 


long 


clump size in bytes 


10 


nxFreeFN 


long 


next free file number 


14 


btClpSize 


long 


B*-tree clump size in bytes 


18 


rsrvl 


word 


reserved 


20 


rsrv2 


word 


reserved 


22 


rsrv3 


word 


reserved 



Trap Macros 

Trap Macro Requiring Routine Selectors 



„Pack2 




Selector 


Routine 


$0000 


DIBadMount 


$0002 


DILoad 


$0004 


DlUnload 


$0006 


DI Format 


$0008 


DIVerify 


$000A 


DIZero 



Global Variables . ^ 

FmtDef aults long Pointer to substitute values for hierarchical volume directories. 



Result Codes 



[no name] 


2 


Disk in specified drive is already mounted 


[no name] 


1 


User canceled initializing 


noErr 


0 


No error 


ioErr 


-36 


I/O error 


paramErr 


-50 


Drive number specified is bad 


volOnLinErr 


-55 


Volume is already online 


nsDrvErr 


-56 


No such drive 
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noMacDskErr -57 Disk is not a Macintosh disk 

extFSErr -58 Disk has external file system 

badMDBErr -60 Master directory block is bad 

lastDskErr -64 Last of the range of low-level disk errors 

f irstDskErr -84 First of the range of low-level disk errors 

memFullErr -108 Not enough memory 
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Glossary 



AppleTalk Filing Protocol (AFP) A protocol 
that allows users to share data files and 
application programs that reside in a shared 
resource, such as a file server. 

asynchronous execution A mode of invoking 
a routine. During the asynchronous execution 
of a routine, an application is free to perform 
other tasks. 



absolute search A search that begins at the root 
directory of the file system hierarchy and always 
descends the hierarchy See also relative search. 

access modes A set of file permissions that 
specify what abilities should be allowed to a 
user attempting to open a file fork. See also 
deny modes. 

access path A description of the route that the 
File Manager follows to access a file; created when 
a fQe is opened. See also file reference number. 

access permissions See access modes, file 
permissions. 

access privileges See directory access privileges. 

access rights The pennissions governing 

the access to a file, or the privileges governing the 

access to a directory. 

activation procedure An application-defined 
procedure that controls the highlighting of 
application-defined dialog items capable of 
receiving keyboard input. 

active field The target of keyboard input in a 
dialog box. 

AFP volume A volume that is accessed using the 
AppleTalk Filing Protocol. 

alias An object in the file system that represents 
another file, directory, or volume. 
Alias Manager The part of the Operating System 
that helps you to locate specified files, directories, 
or voliunes at a later time. The Alias Manager 
creates and resolves aUas records. 

alias record A data structure created by the Alias 
Manager to identify a file, directory, 
or volvune. 

alias target The file, directory, or volume 
described by an alias record. 

allocation block A group of consecutive logical 
blocks on a volume. 



backing-store file The file that the Virtual 
Memory Manager uses to store the contents of 
unneeded pages of memory. 

bad block sparing The process of working 
around a bad block by removing it from the pool 
of available free blocks. 

blank access privileges The directory access 
privileges under which a directory has the same 
access privileges as the directory's parent. 

block A group regarded as a uxut; usually 
refers to data or memory in which data is stored. 
See also allocation block, 

boot blocks The blocks on a disk that contain 
system startup information. 

browsing access The file access permissions 
that allow users to read but not modify a file. 

B*-tree A method of organizing information 
into a collection of nodes. The nodes are arranged 
in a way that allows efficient access to the stored 

information. 

B*-tree control block A block of memory that 
contaii\s information about a B*-tree file (either 
a catalog file or an extents overflow file). 

B*-tree file A file that is organized as a B*-tree. 
See also catalog file, extents overflow file. 

B*-tree header record A record in a header 
node that contains information about the 
begiiming of the tree, as well as the size of 
the tree. 
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catalog file A special file, located on a volume, 
that contains information about the hierarchical 
organization of files and folders on that volume. 

catalog node An entry in a volume's catalog file 
that describes either a file or a directory. 

catalog node ID A unique number assigned 
to a node in a catalog file. For a directory/the 
catalog node ID is the directory ID; for a file, 
the catalog node ID is the file ID. 

closed file A file without an access path. You 
cannot read from or write to closed files. 

clump A group of contiguous allocation blocks. 
Space is allocated to a new file in clumps to 
promote file contiguity and avoid fragmentation- 
clump size The number of allocation blocks to 
be allocated to a new file. 

CNip See catalog node ID. 

CNode See catalog node. 

common parent The lowest-level directory 
that appears in the pathnames of two objects on 
a volume. 

completion routine A routine that is executed 
when an asynchronous call to some other routine 
is completed. 

current directory The directory whose contents 
are listed in the dialog box displayed by the 
Standard File Package. See also default directory. 

current disk The current volume. 

current volume The volume on which the 
current directory is located. 

data buffer A buffer (usually in an application's 
heap) that contains information to be written to 
a file from the application, or read from a file to 
an application. 

data fork The part of a file that contains data 
accessed using the File Manager. 

default directory The directory used in File 
Manager routines whenever you don't explicitly 
specify some directory. See also current directory, 

default volume The volume that contairis the 
default directory. 



deny modes A set of file permissions that 
specify what abilities should be denied to users 
attempting to open a file fork already opened by 
another user See also access modes. 

dialog hook function An application-defined 
function that handles item selections in a dialog 
box displayed by the Standard File Package. 

directory A subdivision of a volume, available 
in the hierarchical file system. A directory can 
contain files and other directories (known as 
subdirectories). 

directory access privileges A set of conventions 
for controlling access to a directory, 

directory ID A unique number assigned to a 
directory. The File Manager uses this number to . 
distinguish a directory from others on the same 
volume. See also catalog node ID. 

disk A physical medium capable of storing 
. information. 

disk cache A part of RAM that acts as an 
intermediate buffer when data is read from 
and written to file systems on secondary 
storage devices. 

disk formatting The process of writing special 
information onto a disk so that the disk driver 
can read from and write to the disk. 

disk initialization The process of making a 
disk usable by the Macintosh Operating System. 

disk initialization dialog box A dialog box 
asking the user whether a disk should be ejected 
or initialized. 

Disk Initialization Manager The part of the 
Macintosh Operating System that manages the 
process of initializing disks. 

disk-inserted event An event generated when 
the user inserts a disk in a disk drive or takes 
any other action that requires a volume to be 
mounted. 

disk switch dialog box A dialog box asking the 
user to insert a particular disk. 

disk verification The process of reading every 
bit on the disk to ensure that the disk has been 
formatted correctly and contains no bad blocks. 
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disk zeroing The process of creating on the 
disk the data structures and files necessary for 
the disk to be recognized as a hierarchical file 
system (HPS) volume. 

display list In a standard file dialog box, the 
list of files, folders, and volumes at one level of 
the display hierarchy, from which the user can 
select items. 

document A file that a user can create and edit. 
A document is usually associated with a smgle 
application, which the user expects to be able to 
open by double-clicking the document's icon in 
the Finder. 

document record An application-defined data 
structure that contains information about the 
window, any controls in the window (such as 
scroll bars), and the file (if any) whose contents 
are displayed in the window. 

drive queue A list of all volumes connected to 
the computer. 

end-of-file (EOF) See logical end-of-file, 
physical end-of-file. 

EOF See logical end-of-file, physical 
end-of-file. 

exclusive access The file access permissions 
that deny other users both read and write access 
to a file. 

exhaustive search A search using an algorithm 
that scans an entire volume to look for possible 
matches. 

extent A contiguous range of allocation blocks 
that have been allocated to some file. 

extent data record A data record that contains 
three extent descriptors. Extent data records are 
stored in the leaf nodes of the extents overflow 
me, in the catalog file, and in the boot blocks. 

extent descriptor A description of an extent, 
consisting of the nim\ber of the first allocation 
block of the extent followed by the length of 
the extent. Defined by the ExtDescr iptor 
data type. 

extents overflow file A special file containing 
all extent data records that are not stored 
elsewhere by the File Manager, 



fast search A search that employs an algorithm 
designed to find the target of an alias record 
quickly. See also absolute search. 

FCB See file control block. 

file A named, ordered sequence of bytes stored 
on a Macintosh volume. A file is divided into a 
data fork and a resource fork. 

file access permissions See file permissions. 

file control block (FCB) A fixed-length data 
structure, contained in the file-control-block 
buffer, where information about an access path to 
a file is stored. 

file-control-block buffer A block in the system 
heap that contains one file control block for each 
access path. 

file filter funcfion An application-defined 
function that helps determine which files appear 
in the list of files to open. This list appears in 
the dialog boxes displayed by the Standard 
File Package. 

file fork One of the two parts of a file. See also 
data fork, resource fork. 

file ID A unique number assigned to a file. The 
File Manager uses this number to distinguish a 
file from others on the same volume. See also 
catalog node ID. 

file ID reference An internal record in the 
volume's catalog file. This record specifies the 
filename and parent directory ID of the file with a 
given file ID. 

file ID thread record See file ID reference. 

file I/O queue A queue containing parameter 
blocks for all I/O requests to the File Manager. 

File Manager The part of the Macintosh 
Operating System that manages the organization, 
reading, and writing of data located on physical 
data storage devices such as disk drives. 

file mark A marker the File Manager uses 
to keep track of its place in a file during a read 
or write operation. The file mark specifies 
the position of the next byte that will be read 
or written. 

filename A sequence of up to 31 printing 
characters, excluding colons, that identifies a file. 



GL-3 



TIVO-408880 



GLOSSARY 



file permissions A set of conventions for 
controlling access to a file. A file's permissions 
consist of access modes and deny modes. 

file reference number A number (greater 
than 0) that is returned to your application when 
it opens a fork of a file using File Manager 
routines; each file reference number corresponds 
to a unique access path. 

file server A computer running software that 
provides network users with access to shared 
disks or other mass-storage devices. 

file system A method of organizing files and 
directories on a volume. 

file system specification A record that identi- 
fies a stored file or directory by volume reference 
number, parent directory ID, and name. Defined 
by the FSSpec data type. 

Fiftder A Macintosh application that allows 
access to documents and other applications. 
The Finder uses icons to represent objects on 
a volume. 

flush To write data from a cache in memory to 
a volume. 

folder A directory. See directory. 

fork * See file fork. 

formatting See disk formatting. 

full pathname A pathname that begins in the 
root directory. 

guest A user who is logged on to a file server 
without a registered user name and password. 

header node The first node in a B*-tree file; it 
contair\s essential information about the entire 
B*-tree file. 

HFS See hierarchical file system. 

HFS volume A volume that is organized 
according to the hierarchical file system. 

hierarchical file system (HFS) A method of 
organizing files and directories on a volume in a 
hierarchical or tree-like structure. 

index node A node containing records that 
point to other nodes in the B*-tree hierarchy. 



initialization See disk initialization. 

I/O queue See file I/O queue. 

I/O request A request for input from or output 
to a file or device driver; caused by calling a File 
Manager or Device Manager routine 
asynchronously. 

leaf node A node that contains data records. 

locked file A file whose data cannot be changed. 

locked range A range of bytes in a file whose 
data cannot be changed. 

locked volume A volume whose data cannot 
be changed. 

logical block A.portion of a volimie. Usually 
512 bytes long. 

logical end-of^file The position of 1 byte past 
the last byte in a file; equal to the actual number 
of bytes in the file. 

log on To connect to a networked file server or 
to a local machine that requires user authentica- 
tion. Usually a user must specify a user name and 
password to be able to log on to a file server. 

Macintosh file system (MFS) A now-obsolete 
method of organizing files on a volume in a "flat" 
or nonhierarchical structure. See also hierarchical 
file system. 

Make Changes privileges The directory access 
privileges that allow other users to create, rename, 
delete, and write files in the specified directory. 

map node A node that contains an additional 
map record. 

map record A record in a header node or map 
node that indicates which nodes in a B*-tree file 
are used and which are not. 

mark See file mark. 

master directory block (MDB) The part of a 
volimf\e that contains iltformation about the 
volimfie, such as the volume name and allocation 
block size. 

MFS volume A volume that is organized using 
the Macintosh file system. 
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modal-dialog filter function An application- 
defined function that filters events passed from 
the Event Manager to the Standard File Package 
when one of its dialog boxes is being displayed. 

modes See access modes, deny modes. 

mount To make a volume available on the 
local machine. 

mounted volume A volume that has had 
its descriptive information read by the File 
Manager and placed into a volume control 
block in memory. 

newline character Any character, but usually 
the Return character (ASCn code $0D), that 
indicates the end of a sequence of bytes. 

newline mode A mode of reading data in 
which the end of the data is indicated by a 
newline character (and not by a specific 
byte count). 

node Apart of aBMree. 

node descriptor The first part of a B*-tree node; 
it contains information about the node, as well as 
forward and backward links to other nodes. 

offline volume A volume that has been 
mounted but made temporarily xmavailable (for 
example, because it was ejected). 

offspring For a given directory, the set of files 
and directories the given directory contains. 

online volume A volume that has been 
mounted and is currently available for File 
Manager operations. 

open file A file with an access path. You can 
read from and write to open files orvly. 

open permission Information about a file that 
indicates whether the file can be read from, 
written to, or both. 

parent directory The directory in which a file or 
directory is located. 

parent directory ID The directory ID of the 
directory containing a file or directory, 

partial pathname A pathname that begins in 
some directory other than the root directory. 



partition A part of a disk that has been allocated 
to a particular operating system, file system, or 
device driver. 

partition map A block of information that 
describes the organization of partitions on a disk. 

password A string of characters that a user or 
application must provide to gain access to a 
networked file server or to a local machine that 
requires user authentication. Passwords are 
frequently encrypted prior to transmission over a 
network to ensure network security. 

pathname A series of concatenated directory 
names and filenames that identifies a given file 
or directory. See also full pathname, partial 
pathname. 

path reference number See file reference 
number. 

permissions See file permissions. 

physical end-of-file The position of 1 byte past 
the last allocation block of a file; equal to 1 more 
than the maximum number of bytes the file 
can contain. 

pointer record The kind of record contained in 
an index node in a B*-tree file. The structure of a 
pointer record depends on the kind of B*-tree in 
which it is contained. 

poor man's search path The list of directories 
that the File Manager searches whenever it cannot 
find a specified file in the specified directoiy. 

preferences file A file that stores a user's 
settings for a document or application. 

Preferences folder A directory located in the 
System Folder that stores preferences files. 

privilege model A set of conventions for 
controlling access to stored files and directories. 

privileges See directory access privileges. 

pseudo-item A constant that does not represent 
any actual item in the dialog list of one of 
the dialog boxes displayed by the Standard 
File Package. 

range locking Locking a range of bytes in a file 
so that other users can't read from or write to 
that range, but allowing the rest of the file to 
be accessed. 
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read privileges See See Files privileges. 

read/write permission Information associated 
with an access path that indicates whether the file 
can be read from, written to, or both, 

relative path A path to the target from another 
file or directory on the same volume. 

relative search A search that starts in a specified 
directory and searches for the target 
of an alias record by ascending the file system 
hierarchy to a predetermined common parent 
of the. target and the starting directory, and 
then descending the hierarchy from that 
common parent. 

resolve To find the target of an alias record. 

resource fork The fork of a file that contains the 
file's resources. 

root directory The directory at the base of 
a volume. 

root node The first index node in a B*-tree. 

search key A piece of data that the File Manager 
uses when searching through a B*-tree to locate 
the information it needs. 

search privileges See See Folders privileges. 

See Files privileges The directory access 
privileges that allow users to read fOes in the 
specified directory. 

See Folders privileges The directory access 
privileges that allow users to see other directories 
. in the specified directory. 

shared access The file access permissions that 
allow other users both read and write access to 
a file, 

shared environment Any operating environ- 
ment that supports multiple users and multiple 
access to data or applications. 

share point A volume or directory made 
available for sharing on the network. 

single-writer access The file access permissions 
that deny other users write access to a file but 
allow them to read it. 



Standard File Package The part of system 
software that allows you to present the 
standard user interface when a file is to be 
saved or opened. 

subdirectory A directory that is contained in 
some other directory. All directories on a volume 
except the root directory are subdirectories. 

synchronous execution A mode of invoking a 
routine. After calling a routine synchronously, an 
application cannot perform other tasks until the 
routine is completed. 

system startup information Certain config- 
urable system parameters that are stored in 
the boot blocks of a volume and read in at 
system startup. 

target See alias target. 

unmounted volume A volume that hasn't yet 
been mounted, or a volume that was previously 
mounted but has since had its volume control 
block removed from the VCB qupue. 

user authentication method A process used 
by a file server or workstation to confirm the 
user's identity. 

user name A string of characters that imiquely 
identifies a user for login purposes. 

VCB See volume control block. 

VCB queue See volume control block queue. 

verification See disk verification. 

volume A portion of a storage device that is 
formatted to contain files. 

volume bitmap A data structure that contains a 
series of bits indicating which blocks on the 
volume are allocated. Volume bitmaps exist both 
on HFS volimies and in memory. 

volume catalog See catalog file. 

volume control block (VCB) A nonrelocatable 
block of memory in the system heap that contains 
information about a specific mounted voltime, 
including the information from the volume's 
master directory block. 
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volume control block queue A list of the 
volume control blocks for all mounted volumes. 

volume index A number identifying the 
position of a mounted volume listed in the 
volume control block queue. 

volume information block (VIB) See master 
directory block. 

volume name A sequence of up to 27 characters, 
excluding colons (:), that identifies a volume- 
volume reference number A unique number 
assigned to a volume when it's mounted; used to 
refer to the volume. 

working directory A temporary directory 
reference by which the File Manager specifies 
both a directory and the volume on which it 
resides. The File Manager assigns a reference 
number to each working directory. 



working directory control block A data 
structure that contains the directory ID of a 
working directory as well as the volume 
reference number of the volume on which the 
directory is located. 

working directory reference number A tempo- 
rary reference number that encodes a directory 
ID and a volume reference number. It can be 
used in place of the volume reference number in 
most File Manager calls. 

write privileges See Make Changes privileges, 
zeroing See disk zeroing. 
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absolute search for alias records 4-6 to 4-7 
access-control fvinctions. See access privileges 
access modes 1-21, 2-7, 2-15 to 2-18 

AFP 2-18 

translation of 2-17 
access paths 1-8,1-21,2-8 

access permissions. See access modes; file permissions 
access privileges 

in A/UX file systems 2-22 

in foreign file systems 2-20 to 2-22, 2-232 to 2-234 
access rights. See directory access privileges; file 

permissions 
activation procedures 3-30 to 3-31, 3-59 
active fields 3-31 
AddDrive procedure 2-236 
AFP (AppleTalk Filing Protocol) 2-20 
AFPVolMountInf o data type 2-110 
AFP volume mounting information records 2-110 
_A1 i a sDi spat ch trap macro 4-28 
aliases 

defined 1-11 

resolution by Finder 1-11 

resolution of by Standard File Package 3-14 ' 
Alias Manager 4-3 to 4-30. See also alias records 

application-defined routines in 4-25 

routines in 4-14 to 4-24 

testing for availability 4-9 

user interface guidelines 4-7 
alias-matching filter function 4-25 
. AliasRecord data type 4-5, 4-14 
alias records 4-4 to 4-5 
. contents 4-4,4-13 

creating 4-9 to 4-10, 4-15 to 4-17 

customizing 4-13 

defined 4-3 

exhaustive search for 4-8 

finding targets of 4-4 

getting information from 4-13,4-23 

private Alias Manager data 4-5 

relative path in 4-6 

resolving 4-5 to 4-8 

functions for 4-10 to 4-11, 4-19 to 4-23 
searches 

absolute 4-6 to 4-7 

exhaustive 4-8 

fast 4-7, 4-10 

relative 4-5 to 4-6 



search strategies 4-5 to 4-8 

storing and retrieving 4-12 

updating 4-13,4-18 
alias targets 4-3 
'alis' resource type 4-8,4-12 
Al locate function 2-118 to 2-119 
allocation blocks 

default size of 5-14 

deternmung number free 2-46 

introduced 2-53,2-56 

size 1-6 to 1-7 
AllocContig function 2-119 
AppFile data type 1-35,1-41 
AppIeShare volumes 

automatic moimting to resolve alias records 4-4 

support for mounting routines 2-110 
AppleTalk Filing Protocol (AFP) 2-20 
application files records 1-41 

asynchronous execution with low-level File Manager 

routines 2-6,2-120,2-238 
asynchTrpBit global constant 2-120 
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B*-tree clumps, default size of 5-14 
B*-tree control blocks 2-83 to 2-84 
B*-tree file structure 2-63 
B*-tree header nodes 2-67 to 2-69 
B*-tree header records 2-68 
B*-tree index nodes 

defined 2-69 

root nodes 2-70 
B*-tree leaf nodes 

for catalog files 2-72 

defined 2-70 
B*-tree map nodes 2-69 
B*-tree map records 2-68 
B*-tree node descriptors 2-64 
B*-tree nodes 2-64 to 2-65 
B*-tiees 2-63 to 2-70 
B*-tree search keys 

for catalog files 2-71 

defined 2-66 
backing-store files 1-4 
bad block sparing 5-7 to 5-9 
Balloon Help 3-19 
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basic File Manager parameter blocks 2-87 to 2-91 
blank access privileges 2-18 
blocks. See also allocation blocks 

logical 2-56 
Boo tBlkHdr datatype 2-57 to 2-59 
boot block header formats 2-57 
boot block headers 2-57 to 2-59 
boot blocks 2-57 to 2-59 
browsing access 2-17 
BTCB data type 2-83 to 2-84 
BTHdrRec data type 2-68 
byte ranges in shared files, locking 2-50 to 2-52 
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callback routines 

with MatchAlias function 4-25 
with Standard File Package routines 3-16, 3-20 to 
3-31 

catalog data records 2-72 to 2-74 
catalog file key records 2-71 
catalog files 1-4, 2-53, 2-70 to 2-74 

searching 2-38 to 2-43, 2-204 to 2-206 
catalog information parameter blocks 2-100 to 2-104 
catalog move parameter blocks 2-104 to 2-106 
catalog node IDs (CNlDs). See also directory IDs; 
file IDs 
defined 2-70 
reserved values 2-70 
catalog nodes 2-70 
catalog position records 2-41, 2-104 
catalogs. See catalog files 
CatDataRec data type 2-72 to 2-74 
CatDataType data type 2-72 
CatiKeyRec data type 2-71 
CatMove function 2-179 to 2-180 
CatPositionRec data type 2-41, 2-104 
CInf oPBRec data type 2-100 to 2-104 
Close command (File menu) 1-12 to 1-14, 1-32 to 1-34 
CI oseWD function 2-181 to 2-182 
closing files 1-32 to 1-34, 1-45 to 1-46, 2-81, 2-114 to 
^-115 

C 1 r AppFi 1 es procedure 1-60 
clumps 

default size of 5-14 

defined 1-8,2-56 
clump size 2-57 

CMovePBRec data type 2-105 to 2-106 
CNIDs. See catalog node IDs 
CNodes. See catalog nodes 
commands, menu. See menu commands 
common parent in alias records 4-6 



compatibility, custom Standard File Package dialog 

boxes 3-40 
completion routines 
for asynchronous File Manager calls 2-238 to 2-239 
defined 2-7 
limitations on 2-239 
CountAppFiles procedure 1-59 
CreateResFile procedure 1-51, 2-157, 2-173, 2-187 
creation dates, handled by FSpExchangeFiles 1-26 
CurDirStore global variable 3-65 
current directory, in Standard File Package dialog 

boxes 3-5,3-31 to 3-34 
current disk. See current volume 
current volume 3-32 to 3-34 

in Standard File Package dialog boxes 3-5, 3-31 to 
3-34 

custom dialog boxes. See dialog boxes, custom 
CustomGetFile procedure 3-51 to 3-52 
CustomPutFile procedure 3-46 to 3-47 
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data buffers 1-9 
data forks 1-4 to 1-5 

creating 1-51,2-157,2-173,2-187 
data organization in memory 2-76 to 2-86 
data organization on volumes 2-52 to 2-76 
'dctb' resource type 3-20 
default directory 2-35 to 2-37 
default volume 2-12, 2-35 to 2-37 
deny modes 2-16 to 2-18 
dialog boxes 

custom 3-8 to 3-12, 3-16 to 3-31 

displaying file types in 3-16 

resources 3-17 

for saving and opening files 3-4 to 3-13 
custom 3-16 to 3-31 
item numbers 3-22 
standard 3-4 to 3-8 
dialog hook functions 3-21 to 3-28, 3-35 to 3-38, 3-56 to 
3-57 

DIBadMount function 5-10, 5-11, 5-18 to 5-19 
DI Format function 5-20 
DILoad procedure 5^16 
DirCreate function 2-173 to 2-174 
directories 

current 3-31 to 3-34 

default 2-35 to 2-37 

defined 1-9 

described for PBCat:Search 2-38 to 2-39 
locking 2-149, 2-161, 2-177, 2-197 
moving 2-179 to 2-180 
naming 2-27 
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directories (continued) 
selecHng 3-10 to 3-12, 3-34 to 3-38 
specifying in HFS 2-29 

in Standard File Package dialog boxes. Sec current 
directory 

UT^Iocking 2-162, 2-178, 2-198 
directory access privileges 2-18 to 2-20, 2-97 
directory IDs 

defined 1-9,2-25 

in resolution of alias records 4-7 
directory records 2-72 
directory thread records 2-73 
disk caches 1-9 
disk formatting 5-5 
disk initialization 5-4 
disk initialization dialog boxes 

alternate layouts for 5-5 to 5-7 

initializing disks without 5-12 to 5-13 

placement of 5-10 

presentation of 5-5 to 5-7 

reinitializing disks 5-11 

variations In 5-6 
Disk Initialization Manager 5-3 to 5-25 

and bad block sparing 5-7 to 5-9 

loading 5-10,5-16 

low-level routines 5-19 to 5-22 

^^^^^^^8 the disk initialization dialog box 5-12 to 

routines in 5-15 to 5-22 

unloading 5-17 
disk initialization warning dialog boxes 5-6 
disk-inserted events 

masking out 5-9 
. receiving in a modal dialog 5-9 

responding to 5-9 to 5-10 
disk naming dialog boxes 5-6 
disk partition maps 2-54 
disk partitions 2-54 
disks 

defined 2-54 

determining whether a disk is valid 5-10 
erasing 5-11 

in the Finder 5-7 
formatting 5-4,5-20 
initializing 5-9 to 5-10. 

overriding the disk iniHalization dialog box 5-12 
to 5-13 

narhing 5-6 

reinitializing 5-11 

verifying formatting of 5-5, 5-21 

zeroing 5-5 
disk switch dialog box 1-11,2-11 
disk verification 5-5 
disk zeroing 5-5 
display list 3-5 



' DITL ' resource type, for default Open and Save 

dialog boxes 3-17 to 3-20 
DIUnload procedure 5-17 
DIVerify function 5-21 
DI Zero function 5-21 to 5-22 
' DLOG • resource type, for default Open and Save 

dialog boxes 3-17 to 3-18 
document 1-4 
document records 1-15 
drive queues 2-84 to 2-86 
defined 2-84 

reading an element's flag bits 2-85 
DrvQEl data type 2-84 
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ejected volumes 2-145 
Eject function 2-133 
end-of-file 

logical 1-7 to 1-8 

physical 1-7 to 1-8 
enhanced Standard File Package routines 3-13 
BORSee end-of-file 

£rase C^sk menu command (Special menu) 5-7 

exclusive access 2-17 

exhaustive search for alias records 4-8 

ExtDataRec data type 2-75 

ExtDescriptor data type 2-75 

extent data records 2-75 

extent descriptors 2-75 

extent key records 2-75 

extents 2-75 

extents overflow files 2-53, 2-74 to 2-76 
ExtKeyRec data type 2-75 
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fast search for alias records 4-7 to 4-8 
FCB. See file control blocks 
FCB data type 2-81 to 2-83 
FCBPBRec data type 2-107 to 2-109 
file access pennissions. See file permissions 
file attributes 
defined 2-39 

specifying in PBCatSearch 2-38 
file control block parameter blocks 2-107 to 2-109 
file control blocks 1-8, 2-81 to 2-83 
file data 1-5 

limitations of using Resource Manager 1-6 

using the File Manager to read 1-5 

using the Resource Manager to read 1-5 
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file filter functions 

for file display list 3-20, 3-55 to 3-56 

for resolving aliases 4-25 
file forks 

data fork 1-4 

deleting 2-37 to 2-38 

resource fork 1-4 

truncating 2-38 
file formats in Standard File Package dialog boxes 3-8 

to 3-10 
file fragmentation 1-8 
file ID reference 

defined 2-25 

routines 2-23 
file IDs 

creating 2-230 

defined 2-24 

deleting 2-231 

functions for marupulating 2-229 to 2-232 
in resolution of alias records 4-7 
resolving 2-229 to 2-230 
tracking files with 2-23 
file ID thread records 2-25, 2-72, 2-74 
file 1/0 queues 2-6, 2-77 
File Manager 2-5 to 2-302 
access-control functions 2-20 to 2-22, 2-232 to 2-234 
application-defined routines in 2-238 to 2-239 
and bad block sparing 5-7 
creating FSSpec records 1-54 to 1-55, 2-34, 2-87, 

2-166 to 2-169 
data structures in 2-86 to 2-112 
exchanging contents of two files 1-53, 2-165 
high-level and low-level routines compared 2-6 
mounting inserted disks 5-9 
.mounting remote volumes 2-219 to 2-222 
organization of data in memory 2-76 to 2-86 
organization of data on volumes 2-52 to 2-76 
'^^.'^i^^g volume information 2-147 to 2-150 
routines in 2-112 to 2-238 

directory manipulation 2-10 

file access 2-112 to 2-131 

file ID 2-229 to 2-232 

file manipulation 2-7 to 2-10 

foreign file system 2-232 to 2-234 

FSSpec 2-154 to 2-169 

HFS 2-169 to 2-208 

shared envirorunent 2-208 to 2-228 

utility 2-235 to 2-238 

volume access 2-132 to 2-154 

volume manipulation 2-11 to 2-12 

working directories 2-11, 2-13 
searching a catalog 2-38 to 2-43, 2-204 to 2-206 
testing for features M4, 2-32 to 2-34 
file marks 1-9 



File menu 

adjusting items in 1-37 to 1-38 

appearance of 1-12 

Close command 1-32 to 1-34 

New command 1-16 

Open command 1-18 to 1-22, 3-13 

Revert to Saved command 1-30 to 1-32 

Save As coitunand 1-26 to 1-30, 3-13 

Save command 1-26 to 1-30, 3-13 

user selections in 1-13, 1-16 to 1-34 
filenames 

searching volumes by 2-38 

specifying in PBCatSearch 2-38 
file permissions 1-21,2-7 
file ranges 

locking 2-50 to 2-51, 2-211 to 2-212 

unlocking 2-51, 2-212 to 2-213 
file records 2-72 
file reference numbers 

defined 1-8,2-23 

and FCB buffer 2-81 
files 

access privileges in foreign file systems 2-20 to 2-22, 

2-232 to 2-234 
adjusting size of 1-8, 1-48, 2-117, 2-118 to 2-119, 2-127 

to 2-128 
closing 1-32 to 1-34 

creating 1-16 to 1-18, 1-51, 2-157, 2-173, 2-187 
defined 1-4 
deleting 2-37 to 2-38 

exchanging data in 1-53, 2-10, 2-148, 2-165 to 2-166, 

2-206 to 2-208 
handling File menu commands 1-13 
moving 2-179 to 2-180 
nanung 2-27 
operung 1-18 to 1-22 
access modes 2-7 

with FSSpec routines 2-154 to 2-156 
with high-level HFS routines 2-169 to 2-172 
with low-level HFS routines 2-183 to 2-186 
Standard File Package 1-42 to 1-43, 3-4 to 3-5, 3-9 

to 3-10,3-49 to 3:54 
while denying access 2-208 to 2-210 

opening at application startup 1-34 to 1-36 

permissions 1-21,2-7 

readinjg data 1-22 to 1-23, 1-45, 2-112 to 2-113, 2-121 
to 2-122 

reading data in newline mode 1-9 
reverting to last saved version 1-30 to 1-32 
saving 1-26 to 1-30, 3-5 to 3-7, 3-8 to 3-9 
saving preferences 1-36 to 1-37 
saving under a new name 1-27 
searching a catalog for 2-38 
specifying in HFS 2-29 
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flies (continued) 

tracking with file IDs 2-23 

user interface for saving and opening 3-3 to 3-65 

writing data 1-23 to 1-26 
file sharing, enabled 2-49 

file system. See hierarchical file system; Macintosh file 

system 

file system specification records 
creating 1-51 to 1-52, 2-34 
defined 1-39,2-86 
introduced 2-24 

with Standard File Package 3-14 
file thread records 2-73 

file types, filgring Standard File Package display lists 

filter functions. See abo file filter funcHons 
alias matching 4-25 
with MatchAlias function 4-25 
modal-dialog filter functions 3-28 to 3-30 
with^S^andard File Package routines 3-16, 3-20 to 

Finder information, specifying in PBCatSearch 2-38 
FmdFolder function 1-14 

flushing a volume 1-24, 1-34, 1-55 to 1-56 2-11 2-79 
2-133 to 2-134, 2-142 to 2-143 ' ' ' 
FlushVol function 1-34, 1-55 to 1-56, 2-12 2-134 
FmtDefaults global variable 5-13, 5-14 
folders. See directories 

foreign file systems, access privileges in 2-20 to 2-22 
2-232 to 2-234 "ro^^, 

forks. See file forks 

; formatting disks 5-20 

FSClose function 1-45 to 1-46, 2-114 to 2-115 

FSMakePSSpec function 1-54 to 1-55, 2-87, 2-166 to 
2-168 

FSpCa tMove function 2-164 to 2-165 
FSpCreate function 1-51 to 1-52, 2-156 to 2-157 

FSpCreateResFileprocedure 1-51, 2-157, 2-173; 2487 
FSpDelete function 1-52,2-159 
.FSpDirGreate function 2-158 

FSpExchangeFiles ftinction 1-25 to 1-26 1I53 2-165 
• to 2-166 ' 

FSpGetFlnfo function 2-160 

FSpOpenDF function 1-50, 2-154 to 2-155 

FSpOpenRes File function 1-51,2-157,2-173 2-187 

FSpOpenRF function 2-155 to 2-156 

FSpRename function 2-163 

FSpRstFLock function 2-162 

FSpSetFInfo function 2-160 to 2-161 

FSpSetFLock function 2-161 to 2-162 

FSRead function 1-44, 2-112 to 2-113 

FSSpec data type 1-12, 1-39, 2-86 

PSWrite function 1-45, 2-113 to 2-114 

full pathnames 2-28 



G 



GetAliasInfo function 4-13, 4-23 to 4-24 
GetAppFiles procedure 1-59 
GetApp Farms procedure 1-58 
GetDrvQHdr function 2-236 
GetEOF function 1-48,2-117 
Get FPos function 1-46 to 1-47, 2-115 
Get FSQHdr function 2-235 
GetVCBQHdr function 2-235 
GetVInf o function 1-56, 2-137 to 2-138 
GetVol function 2-36, 2-134 to 2-135 

GetVolParmsInfoBuffer data type 2-109 
GetVRefNum function 1-57,2-138 
GetWDInfo function 2-182 
guests 2-14,2-218,2-221,2-222 
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HCreate function 2-172 to 2-173 
HCreateResFile procedure 1-51,2-157,2-173 2-187* 
HDelete function 2-174 to 2-175 ' ' 

*hdlg* resource type 3-19 
header nodes. See B*-tree header nodes 
HPS. See hierarchical file system 
hf sBit global constant 2-120 
HFSDe faults data type 5-14 
HFS defaults record 5-14 
HPS directories, creating on a volume 5-13 
HPS parameter blocks 2-91 to 2-100 
HPS specifications 2-28 to 2-30 
HFS volumes 
defined 1-9,2-54 
signature words for 2-60 
structure of 2-56 
HGetFInf o function 2-175 to 2-176 
HGetVol function 2-136 
hierarchical file system (HPS) 
defined 1-9 to 1-11,2-27 
organization of 2-52 to 2-76 
HOpenDF function 2-169 to 2-170 . 
HOpen function 2-171 to 2-172 
HOpenResFile function 1-51, 2-157, 2-173, 2-187 
HOpenRF hmction 2-170 to 2-171 
HParamBlockRec data type 2-91 to 2-100 
HRename function 2-178 to 2-179 
HRstFLock function 2-177 to 2-178 
HSe t Fin fo function 2-176 
HSetFLock function 2-177 
HSetVol function 2-136 to 2-137 
possible problems using 2-36 
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index nodes. See B*-tree index nodes 
initializing disks 5-3 to 5-6, 5-9 to 5-10 

overriding the disk initialization dialog box 5-12 to 
5-13 

I/O queues- See file 1/0 queues 
I/O requests 2-6 



MPS. See Macintosh file system 

MPS volumes, signature words for 2-60 

modal-dialog filter functions, for Standard File Package 

dialog boxes 3-23, 3-28 to 3-30, 3-57 to 3-59 
modes. See access modes; deny modes 
modification dates, handled by 

FSpExchangeFiles 1-26 
mounting volumes. See volumes, mounting 
mounting volumes programmatically 2-219 to 2-222 
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keyboard equivalents, in Standard Pile Package dialog 
boxes 3-7 to 3-8 



L 

leaf nodes. See B*-tree leaf nodes 

loading the Disk Initialization Manager 5-15 to 

locking 

directories 2-161,2-177,2-197 

file ranges 2-50 to 2-52, 2-211 

files 2-161,2-177,2-197 
logical blocks 1-6,2-56 
logical end-of-file 1-7 to 1-8 
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naming disks 5-6 

NewAlias function 4-9,4-15 

HewAliasMinimalFroiuFullPath function 4-10, 

NewAliasMinimal function 4-10,4-16 

New command (Pile menu) 1-12 to 1-14, 1-16 to 1-1 

New Folder dialog box 1-29, 1-40, 3-7, 3-42 

newline character 1-9, 2-90, 2-95, 2-122 

newline mode 1-9, 2-90, 2-95, 2-113, 2-122 

NodeDescriptor data type 2-64 

node descriptors, B*-tree 2-64 

node records 2-66 

nodes, B*-tree 2-64 to 2-65 

nonprinting characters 
using in filenames 2-28 
using in volume names 2-28 



M 

Macintosh file system (MPS) 
defined 2-26 
introduced 2-24 
Make Changes privileges 2-18 

map nodes, B*-tree 2-69 

map records 2-68, 2-69 

marks. See file marks 

master directory block records 2-60 

master directory blocks (MDB) 2-59 to 2-62 

MatchAlias function 4-11, 4-20, 4-25 

MDB. See master directory blocks 

MDB data type 2-60 

menu commands 
aose(FUemenu) 1-12 to 1-14, 1-32 to 1-34 
Erase Disk (Special menu) 5-7 
New (File menu) 1-12 to 1-14, 1-16 to 1-18 
Open (PHe menu) 1-12 to 1-14, 1-18 to 1-22 
Revert to Saved (Pile menu) 1-12 to 1-14, 1-30 to 1-32 
Save (Pile menu) 1-12 to 1-14, 1-26 to 1-30 
Save As (Pile menu) 1-12 to 1-14, 1-26 to 1-30 



o 

offline volumes 1-11,2-11,2-145 

online volumes 2-11, 2-26, 2-145 

Open command (File menu) 1-12 to 1-14, 1-18 to 1-22 

opening files 

at application startup 1-34 to 1-36 
with FSSpec routines 2-154 to 2-156 
with high-level HFS routines 2-169 to 2-172 
with low-level HFS routines 2-183 to 2-186 
with Standard File Package 3-4 to 3-5, S-9 
while denying access 2-208 to 2-210 
OpenResFile function 1-51, 2-157, 2-173, 2-187 
OpenWD function 2-180 to 2-181 
organization of data 
in memory 2-76 to 2-86 
on volumes 2-52 to 2-76 
organization of disks 2-54 

original Standard File Package procedures 3-40 to 3^1, 
3-43 
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_Pack2 trap macro 5-24 
_Pack3 trap macro 3-65 
ParamBlockRec data type 2-87 to 2-91 
parent directories 1-11,2-27 
parent directory IDs 1-11 
partial pathnames 2-28 
partition maps 2-54 
partitions 2-54 

passwords. See user passwords 

pathnames 2-28, 2-29, 2-45 to 2-46 

path reference numbers. See file reference numbers 

PBAllocate function 2-129 

PBAllocContig function 2-130 

PBCat Move function 2-200 to 2-201 

PBCatSearch function 2-38 to 2-43, 2-204 to 2-206 

PBClose function 2-124 

PBCloseWD fimction 2-202 to 2-203 

PBCreateFilelDRef function 2-230 to 2-231 

PBDeleteFilelDRef function 2-231 to 2-232 

PBDirCreate function 2-188 

PBEject function 2-141 

PBExchan^eFiles function 2-206 to 2-208 

PBFlushFile function 2-131 

PBFlushVol function 2-143 

PBGet Cat Info function 2-190 to 2-192 

PBGetEOF function 2-127 

PBGetFCBInfo function 2-237 to 2-238 

PBGetForeignPrivs function 2-232 to 2-233 

PBGetFPos function 2-125 

PBGetUGEntry function 2-216 

PBGetVol function 2-150 to 2-151 

PBGetVolMount Info function 2-220 to 2-221 

PBGetVolMountlnfoSize function 2-219 to 2-220 

PBGetWDInf o function ,2-203 to 2-204 

PBHCopyFile function 2-226 to 2-227 
PBHCr eat e function 2-186 to 2-187 

PBHDelete function 2-189 
PBHGetDirAccess function 2-217 
PBHGetFInf o function 2-194 to 2-195 
PBHGetLoglnInf o function 2-223 
PBHGetVInfo function 2-144 to 2-146 
PBHGetVol hmction 2-152 
PBHGetVolParms hmction 2-34, 2-147 to 2-150 
PBHMapID function 2-224 
PBHMapName function 2-225 
PBHMoveRename function 2-227 to 2-228 
PBHOpenDeny function 2-208 to 2-209 
PBHOpenDF function 2-183 to 2-184 
PBHOpen function 2-185 to 2-186 
PBHOpenRFDeny fimction 2-210 
PBHOpenRF function 2-184 to 2-185 
PBHRename fimction 2-198 to 2-199 
PBHRstFLock function 2-197 to 2-198 



PBHSetDirAccess fimction 2-218 
PBHSetFInfo function 2-195 to 2-196 
PBHSetFLock function 2-196 to 2-197 
PBHSetVol function 2-36, 2-153 to 2-154 
PBLockRange function 2-50 to 2-52, 2-211 to 2-212 
PBMakeFSSpec function 2-168 to 2-169 
PBMount Vol function 2-139 to 2-140 
PBOff Line function 2-142 
PBOpenWD function 2-201 to 2-202 
PBRead function 2-121 to 2-122 
PBResolveFilelDRef function 2-229 to 2-230 
PBSetCatInf o function 2-193 to 2-194 
PBSetEOF function 2-127 to 2-128 
PBSetForeignPrivs function 2-234 
PBSetFPos function 2-126 
PBSetVInf o hmction 2-146 to 2-147 
PBSetVol function 2-151 
PBShare function 2-214 

PBUnlockRange function 2-51, 2-212 to 2-213 
PBUnmountVol function 2-140 to 2-141 
PBUnshare function 2-215 
PBVolumeMount function 2-221 to 2-222 
PBWrite function 2-122 to 2-123 
permissions 

AFP 2-18 

file 2-7 

shared access 2-16 
physical end-of-file 1-7 to 1-8 
pointer records 2-70 
poor man's search paths 2-31 
pop-up menus, in Standard File Package dialog 

boxes 3-9 
preferences files 1-4, 1-36 to 1-37 
Preferences folder 1-11 
privilege information 

in A/UX file systems 2-22 

in foreign file systems 2-20 to 2-22 
privilege models 2-20,2-21 
privileges 2-18 
pseudo-items 3-22 to 3-26 

constant descriptions 3-22 to 3-27 
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radio buttons, in Standard File Package dialog 

boxes 3-8 
range locking. See locking file ranges 
reading data fix>m files 1-22 to 1-23, 1-44 2-112 to 

2-113, 2-121 to 2-122 
read privileges. See See Files privileges 
records, alias. See alias records 
relative paths 4-6 

relative search for alias records 4-5 to 4-6, 4-7, 4-8 
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reply records for Standard File Package 3-13 to 3-14, 

3-41 to 3-44 
ResolveAlias function 4-lQ, 4-19 
resolving alias records 4-10 to 4-11 
controlling search algorithms 4-11 
multiple targets 4-11 
a single target 4-10 to 4-11 
resource editors 3-18 
resource forks 1-4 

creating 1-51,2-157,2-173,2-187 
creating resource map in 1-51, 2-157, 2-173, 2-187 
resource types 
'alis' 4-8,4-12 
►dctb' 3-20 
•DITL' 1-29,3-7 
•DLOG' 3-17 
'hdlg* 3-19 
Revert to Saved command (File menu) 1-12 to 1-14, 

1-30 to 1-32 
Rez 3-17 

root directory 1-10 

root nodes. See B*-tree index nodes 



Save As command (File menu) 1-12 to l-14,J-26 to 1-! 
Save command (File menu) 1-12 to 1-14, 1-26 to 1-30 
saving files 1-26 to 1-30 
saving to different file formats 3-8 
scripts, specifying when creating a file 1-51, 2-157 
search keys, B*-tree 

for catalog files 2-71 

defined 2-66 
search paths 2-31 

search privileges. See See Folders privileges 
search strategies in resolution of alias records 4-5 to 
absolute 4-6 
. . . exhaustive 4-8 
fast 4-7 
relative 4-5 
See Files privileges 2-18 
See Folders privileges 2-18 
SetEOF function 1-8, 1-48 to 1-49, 2-117 to 2-118 
Set FPos function 1-47,2-116 
SetVol function 2-36, 2-37, 2-135 
SFGetFile procedure 3-53 
SFPGet File procedure 3-54 
SFPPutFile procedure 3-48 to 3-49 
SFPutFile procedure 3-47 to 3-48 
SFReply data type 3-43 
SFSaveDisk global variable 3-65 



shared access 2-17 
shared environments 2-14 to 2-22 

routines 2-14 to 2-15 
share points 2-14, 2-48 to 2-49 
signature words 

default for HFS volumes 5-14 
for HFS volumes 2-60 
for MFS volumes 2-60 
single-writer access 2-17 
Special menu. Erase Disk command 5-7 
Standard File Package 3-3 to 3-65 

activation procedures 3-30 to 3-31, 3-59 
and aliases 3-14 

application-defined routines in 3-55 to 3-59 
callback routines 3-20 to 3-31 
compatibility with earlier procedures 3-40 to 3-41 
data structures in 3-41 to 3-44 
dialog hook functions 3-21 to 3-28, 3-56 to 3-57 
and disk initialization 5-5 
file filter hmctions 3-20 to 3-21, 3-55 to 3-56 
modal-dialog filter functions 3-28 to 3-30, 3-57 to 3-59 
opening files 1-42 to 1-43, 3-4 to 3-5, 3-49 to 3-54 
original procedures 3-40 to 3-41 
original reply record 3-43 to 3-44 
reply records 1-39 to 1-41, 3-13 to 3-14, 3-42 to 3-44 
routines in 3-44 to 3-54 
saving files 1-43, 3-5 to 3-14, 3-44 to 3-49 
-30 testing for features 3-13 

user interface guidelines 3-12 to 3-13 
user interfaces 
custom 3-8 to 3-12 
standard 3-4 to 3-8 
StandardFileReply data type 3-14, 3-42 
StandardGetFile procedure 1-42 to 1-43, 3-4 to 3-5, 
3-14,3-50 

StandardPutFile procedure 1-43, 3-5, 3-45 
stationery pads, handled by Standard File 
4-8 Package 1-40, 3-43 

subdirectories 1-10 

synchronous execution with low-level File Manager 

routines 2-6 
System Folder 1-11 

system software version 7.0 2-24, 2-81, 3-13, 3-26, 3-29, 

3-40,4-4, 5-5,5-10 
system startup ii\formation 2-57 



targets, of an alias record 4-3 
TwoIntsMakeALong data type 2-47 
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unlocking 

directories 2-162, 2-178, 2-198 

file ranges 2-212 

fUes 2-162,2-178,2-198 
Unmount Vol function 2-132 to 2-133 
UpdateAlias function 4-13,4-18 
update events, and Standard File Package routines 3-29 
user authentication methods 2-111, 2-222 
user interface 

for initializing and naming a disk 5-5 to 5-7 

for saving and opening files 3-3 to 3-65 
user interface guidelines 3-12 
user names 2-223 
user passwords 2-112 
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VCB data type 2-78 

VCB queues. See volume control block queues 
VCBs. See volume control blocks 
verifying formatting of disks 5-21 
VIBs. See volume information blocks 
VolMountlnfoHeader data type 2-110 
volume attributes buffers. 2-109 
volume bitmaps 2-53,2-62 
volume catalogs. See catalog files 
volume characteristics 

changing defaults 5-13 to 5-14 

reverting back to defaults 5-14 
volume control block queues 2-78 
volume control block records 2-78 
volume control blocks (VCBs) 1-10, 2-77 to 2-81 
volume index 2-31 

volume information blocks (VIBs) 2-59 
volume mounting information records 2-110 
volume passwords 2-112, 2-221 
volume reference numbers 1-10,2-26 
volumes 

current 3-32 

default 2-35 to 2-37 

defined 1-6, 2-54 

determining if sharable 2-48 

ejected 2-145 

ejecting 2-141 

flushing buffers 2-12 

free space on 2-46 to 2-48 

HFS 2-54 to 2-57 

identified in FSSpec records 2-87 
identifying in an alias resolution 4-6 
indexed searching 2-14 



mounting 1-10, 2-11, 2-20/2-139 to 2-140, 2-219 to 

2-222 
naming 1-10, 2-27 
offline 1-11,2-11,2-145 
online 2-11,2-26,2-145 
orgaruzation of '2-52 to 2-57 
passwords 2-112, 2-221 
placing offline 2-26,2-142 
recursive searching in 2-14, 2-43 to 2-44 
remote mounting of 2-20 

searching 2-13 to 2-14, 2-38 to 2-204 to 2-206 
selecting 3-10 to 3-12, 3-38 to 3-40 
specifying 2-29 

in Standard File Package dialog boxes. See current 
volume 

uiunounting 2-11, 2-140 to 2-141 
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WDPBRec data type 2-106 

working directories 2-180 to 2-182, 2-201 to 2-204 
closing 2-181 to 2-182, 2-202 to 2-203 
defined 2-26 

getting information about 2-182, 2-203 to 2-204 
opening 2-180 to 2-181, 2-201 to 2-202 
working directory control blocks 2-27 
working directory parameter blocks 2-106 
working directory reference numbers 1-15, 2-26 
write privileges. See Make Qianges privileges 
writing data to files 1-23 to 1-26, 1-45, 2-113 to 2-114, 
2-122 to 2-123 
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Files 

]nside Macintosh: Eles describes the parts of the Macintosh Operating System that allow you to manage files 
and other objects in the file system. If your application creates or manipulates files, directories, or volumes, 
you should read this book. 

Inside Macintosh: Files shows in detafl how your application can handle the commands typically found in 
the File menu. This book also provides a complete technical reference for the File Manager, the Standard File 
Package, the Alias Manager, the Disk Initialization Manager, and other file-related services provided by the 
system software. With this book, you'll learn how to 

■ create, open, update, save, and close files 

■ customize the user interface for opening and saving files 

■ search for specific files or directories on a volume 

■ obtain information about files or directories on a volume 

■ manage shared files 

■ keep track of specific files, even if they are moved, renamed, or restored from 
backup 

■ initialize disks and erase contents of previously initialized disks 

■ perform other advanced file-related operations 

To use this book, you should be familiar with the general structure of a Macintosh 
application and with basic memory-management techniques. Both of these topics 
are discussed at length in iTiside Macintosh: Overview, 

Additional aspects of the Macintosh Operating System are discussed in Iriside 
Macintosh: Memory, Inside Macintosh: Processes, Inside Macintosh: 
Operating System Utilities, znd Inside Macintosh: Devices, 

Inside Macintosh is a collection of books, organized by topic, 
that describe the system software of Macintosh computers. 
Together, these books provide the essential reference for 
programmers, designers, and engineers. A graphic overview of 
Inside Macintosh appears on the page facing the inside back 
cover of this book. 



Apple Computer, Inc. 
20523 Mariani Avenue 
Cupertino, CA 95014 
408-996-1010 
TLX 171-576 



Addison-Wesley Publishing Company 




This Page is Inserted by IFW Indexing and Scanning 
Operations and is not part of the Official Record 

BEST AVAILABLE IMAGES 

Defective images within this document are accurate representations of the original 
documents submitted by the applicant. 

Defects in the images include but are not limited to the items checked: 

0^BLACK BORDERS 

□ IMAGE CUT OFF AT TOP, BOTTOM OR STOES 

□ FADED TEXT OR DRAWING 

□ BLURRED OR ILLEGIBLE TEXT OR DRAWING 

□ SKEWED/SLANTED IMAGES 

□ COLOR OR BLACK AND WHITE PHOTOGRAPHS 

□ GRAY SCALE DOCUMENTS 

□ LINES OR MARKS ON ORIGINAL DOCUMENT 

□ REFERENCE(S) OR EXHIBIT(S) SUBMITTED ARE POOR QUALITY 

□ OTHER: 

IMAGES ARE BEST AVAILABLE COPY. 
As rescanning these documents will not correct the image 
problems checked, please do not report these problems to 
the IFW Image Problem Mailbox. 



